HireLens Trello MCP Server

A small MCP server that gives the HireLens Dust agent read/write access to one Trello board: the "Post-sales SE hiring" pipeline. It exposes exactly three tools — get_card, add_comment, set_description — and no business logic. Everything about what HireLens writes and when lives in the agent's own prompt, not in this code.

How it fits together

1. A human moves a card between lists on the Trello board.
2. A Trello Butler rule fires a webhook to Dust (already set up, outside this repo).
3. Dust starts the HireLens agent with the card URL.
4. HireLens calls get_card on this server to read the card (name, current list, description, every comment oldest-first).
5. HireLens compares that against an evaluation grid (a Google Doc, connected to Dust natively) and drafts a summary.
6. HireLens calls add_comment and set_description on this server to write the summary back to the card.

This server only implements step 4 and step 6: moving data in and out of Trello. It does not decide what to write, does not move cards, does not set due dates or labels.

Repository layout

• server.py — the MCP server: declares the three tools, wires up Streamable HTTP, and rejects any request without the right Bearer token.
• trello_client.py — the actual HTTP calls to Trello's REST API (httpx, no third-party Trello wrapper), plus the board-scoping guard and readable error messages.
• smoke_test.py — calls the three Trello functions directly (no MCP, no server) against a real test card. Run this first whenever something seems broken.
• requirements.txt — pinned dependencies.
• .env.example — the four environment variables this server needs.

Setup from zero

git clone https://github.com/PaulHERVET123/trello-mcp-hirelens.git
cd trello-mcp-hirelens
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Fill in .env (see "Getting Trello credentials" below for the first two):

• TRELLO_API_KEY / TRELLO_TOKEN — from your Trello Power-Up.
• TRELLO_BOARD_ID — the board's long id (not the shortLink from the URL). Get it with:

  curl "https://api.trello.com/1/boards/<shortLinkFromBoardUrl>?fields=id&key=<key>&token=<token>"
  

• MCP_AUTH_TOKEN — any random string, e.g. openssl rand -hex 32. This is the Bearer token Dust must send on every request.

Getting Trello credentials

1. Go to https://trello.com/power-ups/admin, click New, create a Power-Up (the name doesn't matter — it's never published, it just anchors an API key to your account).
2. Open it, go to the API key tab. Copy the key.
3. Build this URL yourself (don't click the "Token" link on that page — it doesn't let you restrict scope) and open it in your browser:

   https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=<your key>
   

4. Click Allow. The page shows a long token — that's TRELLO_TOKEN.

Run it locally

source .venv/bin/activate
python smoke_test.py https://trello.com/c/<shortLinkOfATestCard>

If that prints three green "OK"s, the Trello side works. Then start the server:

uvicorn server:app --host 0.0.0.0 --port 8000

Test with MCP Inspector (no Dust involved)

The Inspector ships with a headless CLI mode, which is more reliable to script than the web UI:

npx -y @modelcontextprotocol/inspector --cli \
  --server-url http://localhost:8000/mcp --transport http \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  --method tools/list

You should see a JSON listing of the three tools. To call one:

npx -y @modelcontextprotocol/inspector --cli \
  --server-url http://localhost:8000/mcp --transport http \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  --method tools/call --tool-name get_card --tool-arg cardUrl=https://trello.com/c/<shortLink>

If you'd rather click through a UI: run npx -y @modelcontextprotocol/inspector (no --cli), it opens a browser tab. Click Add Servers → + Add manually, set Transport Type to Streamable HTTP, URL to http://localhost:8000/mcp, add a header Authorization: Bearer <your MCP_AUTH_TOKEN>, connect, then open the Tools tab.

Deploying (Render)

This repo is connected to a Render Web Service (Starter plan, $7/mo, always-on — the free tier sleeps after 15 minutes of inactivity, which risks a timeout mid-demo).

• Build command: pip install -r requirements.txt
• Start command: uvicorn server:app --host 0.0.0.0 --port $PORT
• Environment variables: the same four as .env, set in the Render dashboard.
• Pushing to main auto-redeploys.

Redeploying from scratch

If Render's account/service ever needs to be rebuilt:

1. dashboard.render.com → New + → Web Service.
2. Connect the trello-mcp-hirelens GitHub repo, branch main.
3. Runtime: Python 3. Build/start commands as above.
4. Instance type: Starter (not Free).
5. Add the 4 environment variables.
6. Deploy. The public URL is https://<service-name>.onrender.com.

Emergency fallback (not a normal workflow)

If Render has an outage the morning of the demo:

cloudflared tunnel --url http://localhost:8000

This prints a temporary public HTTPS URL in seconds. Point Dust at <that-url>/mcp instead. Requires the server running locally (uvicorn server:app --host 0.0.0.0 --port 8000) and cloudflared installed (brew install cloudflared).

Declaring the server in Dust (steps 7–9)

1. In Dust, go to Spaces → Tools → Add Tool → Add MCP Server.
2. Enter the server URL including the /mcp path: https://trello-mcp-hirelens.onrender.com/mcp (the bare domain returns 404 — the MCP endpoint only exists at /mcp).
3. Choose Bearer token as the authentication method, paste the value of MCP_AUTH_TOKEN. What you should see: after a short sync, the three tools (get_card, add_comment, set_description) appear listed under the new server, each with its description. What you'll see if it fails: a connection error at sync time almost always means either the URL is missing /mcp, or the Bearer token doesn't match — check Render's logs for a 401 line if so.
4. Set every tool's approval level to Never ask. (We couldn't find the exact screen for this ahead of time — Dust's docs don't cover it for a custom remote server, only the concept exists in their code. It's most likely a dropdown next to each tool either where you add it to the agent, or on the server's tool list itself. Note here exactly where you found it, once you have.)
5. Add the three tools to the HireLens agent's Tools & Knowledge section.
6. Move a test card between lists on the board to fire the webhook, then check the agent's conversation history in Dust — a new conversation should appear showing the tool calls it made. What you'll see if it fails: if the agent's run shows no tool call at all, the webhook/trigger side is the problem (outside this repo's scope). If it shows a tool call that errors, the error message should be readable English explaining what went wrong (that's exactly what trello_client.py was built to produce) — read it, it's meant for you as much as for the agent.

When it breaks

Symptom	Likely cause	Fix
Dust sync fails when adding the server, or every call times out	Free-tier-style cold start, or wrong URL	Confirm the URL ends in /mcp; confirm the Render service shows "Live", not "Sleeping"
Tool call fails with a 401-shaped message	Bearer token mismatch between Dust and MCP_AUTH_TOKEN on Render	Re-copy the exact value from Render's env vars into Dust's Bearer token field
get_card says "This card belongs to board X, not the configured board"	Card URL is for a different board than TRELLO_BOARD_ID	Expected behavior — this is the board-scoping guard working. Confirm you're testing on the right board
Error mentioning "invalid app token" or "invalid key"	Trello token/key was revoked, or wrong values in Render's env vars	Regenerate via the Power-Up admin page, update Render's environment variables, redeploy
Everything worked yesterday, nothing responds today	Render had an incident, or the free-tier-adjacent cold start crept back in somehow	Check Render's status page and this service's logs; fall back to the cloudflared tunnel if it's demo day

Write-up material

Use case. Interviewers on the "Post-sales SE hiring" Trello board write free-form comments as a candidate moves through the pipeline. HireLens reads all of that when a card changes list, compares it to an evaluation grid, and writes a consolidated summary back — so the next interviewer doesn't have to re-read a scattered comment thread.

How it works. Three MCP tools, one Trello REST call each (or two, for get_card, which fetches name/description/list/comments in a single Trello API call using the fields, list, and actions query parameters). No sorting, filtering, or summarization happens in this code — that's entirely HireLens's job, driven by its prompt.

How it was validated. Three layers, each independently: (1) smoke_test.py against a real Trello test card, calling trello_client.py directly; (2) the MCP Inspector's CLI mode, talking real MCP protocol to the server running locally, with no Dust involved; (3) the same Inspector CLI calls against the deployed Render URL, over HTTPS, with the real Bearer token. All three are reproducible with one command each (see above).

Assumptions.

• A single Trello account (mine) backs the token; HireLens acts as me. Its comments are prefixed HireLens specifically so they're distinguishable from a human interviewer's in the same account.
• Comment volume per card stays well under Trello's 50-actions-per-API-page limit; pagination was not implemented because handling it would mean the code deciding what to prioritize, which is scope explicitly left to the agent.
• TRELLO_TOKEN never expires; it can be revoked and regenerated from the Power-Up admin page at any time if that becomes a concern.

Tradeoffs.

• Full description replacement vs. patching between markers. Replacing the whole description is simpler and was chosen for that reason. A marker-based patch (<!-- dust:start -->...<!-- dust:end -->) would cost roughly 15–20 extra lines and 15–20 minutes, but it introduces a business rule (what to do if markers are missing or duplicated) that the spec says belongs in the agent's prompt, not in this tool.
• Three single-purpose tools vs. two macro-tools. Fewer round-trips with macro-tools, but a single contract mixing two intents complicates error messages and removes the agent's ability to update just one of the two. Three tools, one responsibility each, were chosen for that reason.
• DNS-rebinding protection disabled. The MCP SDK's Streamable HTTP transport rejects requests by Host header unless explicitly allow-listed, by default — a protection against malicious webpages targeting a local dev server from a browser. That threat model doesn't apply to a server-to-server call from Dust's infrastructure, and it broke calls from Render's own domain, so it's turned off; the Bearer token check is the real access boundary here.

Limits.

• No retries on Trello API failures (429/5xx) — a failed call surfaces as a readable error to the agent, which can decide to retry or not. Adding retry logic here would duplicate a decision that's arguably the agent's to make.
• No handling of a webhook firing twice for the same move — nothing here is idempotent (add_comment would post twice). Out of scope: the spec says this server does no business logic, and de-duplication is exactly that.
• Single Trello account/token: every write appears to come from me, not from an identifiable "HireLens" service account. Documented as an accepted limitation of the assignment's dataset, not something to fix in code.

Why this approach vs. reasonable alternatives. Syncing Trello into a Dust datasource was ruled out because a datasource is read-only by construction — it cannot write a comment or a description back to Trello, which is half of what this integration needs to do, regardless of how it's kept fresh. No native Dust tool covers Trello or generic HTTP requests either (checked against Dust's own tool/connection list), so a bridge had to be built one way or another. MCP was chosen over a bespoke HTTP-calling layer because it gives the agent a structured, self-describing contract — three named tools with typed arguments and English descriptions — that the LLM can discover and invoke on its own, instead of requiring custom code to decide which endpoint to call and how to parse the response.

Ideas considered and deliberately not built

• Marker-based description patching, so a human's handwritten note in the description could never be overwritten by HireLens. Estimated cost: ~15–20 lines, ~15–20 minutes. Left out because it encodes a business decision (what counts as "the agent's section") that the spec keeps out of this server's code.
• Two macro-tools (get_card_context / write_card_update) instead of three primitives. Would reduce agent↔tool round-trips, at the cost of mixing two intents behind one contract and losing the ability to update only one field.
• Comment pagination for cards with more than 50 comments. Not implemented — see "Assumptions" above.