Skip to content

v5 — MCP v2 and Progressive Tool Disclosure

Latest

Choose a tag to compare

@IBJunior IBJunior released this 14 Nov 12:30
bffcfa9

Every MCP server you connect no longer rides along on every model call.

v4 moved Cameron's traces onto infrastructure you control. This release is about the connectors. Cameron's MCP client moves from the v1 SDK to v2, and it stops binding every connected tool into the context up front. MCP tools get the same progressive disclosure skills got in v3: the model sees a one-line summary per server, and a tool's full definition only once it has asked for it.

Built in public alongside the Agentailor blog, with one tagged release per article. The series hub, including where the roadmap goes next, is at blog.agentailor.com/cameron.

📖 The guide for this release: check the Agentailor blog for the latest guide on this release.

⚠️ Upgrading an existing install? Back up first, then set a key.

  • This release includes migrations 0004–0006. 0006 creates a database role and revokes a function from PUBLIC, so migrations must run as a superuser. All three compose stacks already do. Take a pg_dump before the next docker compose --profile full up (see AGENTS.md).
  • Add CAMERON_SECRET_KEY to .env (openssl rand -base64 32) and keep it out of your database backups. Losing it means re-entering your MCP credentials.
  • Recreate any MCP server you added before this release, so its credentials are stored encrypted. Until then its plaintext values still read as before.

What's new in v5

🔎 MCP tools load on demand (#56)

Every enabled MCP server used to be connected on each request, with all of its tools sent to the model. Context grew with every server, tool choice got worse, and each server cost a connection whether it was used or not.

Now the model sees a short list of capabilities and one tool, load_tools. It searches a cached catalog of every server's tools (BM25) and adds the best matches to the model's tools for the rest of the thread. A server connects only when one of its tools is called, through a pooled connection that closes after 5 idle minutes.

  • Loaded tools are appended and never removed, because changing the tool list costs a prompt-cache miss. Schemas are sent exactly as the server lists them.
  • Servers that need sign-in are detected from stored OAuth state without connecting. load_tools tells the model to ask for a reconnect on the Connections page instead of loading their tools.
  • Each server gets a one-line description: one you write on the Connections page, or one generated on your own model when its tool list changes.
  • With no MCP server enabled, nothing changes: no load_tools, no capability list, the same prompt and tools as before.

The logic is a workspace package of its own, packages/mcp-disclosure, which imports no app code and no MCP client library. Full design: docs/MCP_DISCLOSURE.md.

🔌 MCP SDK v2 (#57)

Cameron now uses @langchain/mcp-adapters 2.x on the MCP TypeScript SDK v2. @modelcontextprotocol/sdk (v1) is gone, along with its pnpm override. Tool names are the adapter's own server_tool, and the disclosure package builds the same names, so the tool the model is shown and the tool that runs carry one name. Elicitation is turned off per server, because v2 raises it as an interrupt the approval flow can't answer and the thread would hang.

Live-testing against a Keycloak-backed MCP server turned up three OAuth bugs the starter shipped with:

  • Registration was rejected because the client metadata hardcoded scope: "read write". Sign-in now delegates to the SDK's auth(), which takes the scope from the server and sends PKCE and the RFC 8707 resource parameter.
  • The Connect button never appeared for a new server, because nothing recorded an OAuth status on add. Saving an HTTP server now probes it, and a 401 at connect time records REQUIRED or EXPIRED.
  • The callback dropped parameters, so the SDK couldn't check iss (RFC 9207). It now forwards them all.

🧭 A deleted server no longer stops the agent silently (#60)

Deleting an MCP server mid-thread made the agent stop with no error. Three gaps lined up: loaded tools vanished with their server's catalog row, the model then called the tool from memory with arguments that didn't parse, and the agent never runs a malformed call, so the turn just ended. Each one is fixed:

  • A loaded tool's definition is saved in the thread, so it stays offered, and a call to it returns server_unavailable, pointing at the Connections page.
  • A malformed tool call is retried up to 2 times with a correction that is never saved to the thread. After that the reply ends with a visible notice.
  • Results the middleware answers itself are streamed live, instead of appearing only after a reload and being reported as awaiting approval.

Keeping the third rule as connectors arrive

Connecting servers puts credentials in Cameron's database and untrusted text in its context. Two changes keep the third rule (all financial data stays on infrastructure the owner controls) intact under that.

🔐 run_sql reads only the finance tables (#58). run_sql ran as the app's own database user inside a READ ONLY transaction, which blocked writes but not reads. A single SELECT could read MCP OAuth tokens, every conversation's checkpoints, config and thread. Since MCP tools auto-approve, text injected into a tool result could have led the agent to read those secrets and send them out through another tool, with no approval card along the way. Now every query runs as a cameron_analytics role that can SELECT transaction and category and nothing else. Postgres decides, not a filter in code. Testing found a way around SET ROLE (set_config('role', 'none', true) is SET ROLE as a function call), so the migration revokes it from PUBLIC and ends with a check that fails if the role can still read mcp_server. A test fails if the role's grants and the schema the agent is shown ever differ.

🔒 MCP credentials encrypted at rest (#59). Env values, headers, OAuth tokens and client info are sealed with AES-256-GCM under CAMERON_SECRET_KEY, so a pg_dump, a file in backups/ or an exposed Postgres port no longer yields usable secrets. The row id and column are bound into each envelope, so a value copied to another row won't decrypt. An install with no credentials needs no key; writing a credential without one fails rather than storing plaintext.

MCP tools still run without approval, as they did before this release. Gating every MCP tool is planned separately.

Also in v5

📋 A README that says what to install (#55). The quick start lists the prerequisites up front and documents pnpm db:seed, which was already in the repo.

✅ The release workflow keeps hand-written releases (#53). The tag run failed whenever a release had already been published by hand. It now leaves an existing release untouched. v5 is its first real run.