NOTE-02PRG-05 — AI-NATIVE

MCP Toolchains in Production

2026-07-02 · 6 MIN · FILED BY OPR-01

The Model Context Protocol did for agent integrations what USB did for peripherals: it turned every "custom connector project" into a socket. On a recent engagement we wired Claude agents into a 40-repo engineering estate — issue tracker, CI, artifact registry, deploy system — as a set of MCP servers. The protocol part was easy. Everything we'd warn you about is on the tool-design side.

Tools are an API for a very fast junior engineer

Design tools the way you'd design an API for a brilliant, tireless colleague with no institutional memory. Our rules, learned the annoying way:

Small and typed. One tool, one verb. A deploy_service tool that also migrates the database will eventually do both when you wanted one.
Idempotent by default. Agents retry. If calling a tool twice does something different from calling it once, you have built a footgun with a JSON schema.
Return state, not prose. Tools that answer with paragraphs get paraphrased; tools that answer with structured state get reasoned about. Save the prose for the model's reply to the human.
Errors are instructions. "error": "branch is stale, run sync_branch first" converts a stuck agent into a self-correcting one.

The authz boundary lives in the server, not the prompt

Nothing in a system prompt is an access control. Every MCP server we ship enforces its own authorization with the calling user's identity, scoped per tool:

tool: merge_pull_request
scopes:
  - repo:{name}:write          # caller must hold it
  - branch:{target}:unprotected OR approval:present
audit:
  log: caller, agent_run_id, args_hash, decision
  sink: append-only, 400-day retention

The agent's role is allowed to request anything; the server decides what executes. When a security review asks "what can the agent actually do?", the answer is a list of server-side scope checks, not a prayer about prompt wording.

The audit log is the product

Six weeks in, a deploy went out with a config change nobody remembered approving. The append-only tool log settled it in four minutes: the change was requested by a human in a ticket, executed by an agent, approved by the on-call — working exactly as designed, and provably so. That log converted the biggest skeptic on the client's staff. Log every call: caller, arguments hash, decision, result. Storage is cheap; trust is not.

FAILURE MODES WE NOW TEST FORTool-output injection (a repo README telling the agent to call other tools), retry storms against non-idempotent tools, stale-context writes, and scope-creep via tool composition. Every toolchain ships with a red-team eval that attempts all four.

Keep the fleet boring

Production agent fleets should be the most boring software you run: pinned model versions, versioned tool schemas, canary agents on a slice of traffic, and evals on every model or schema revision. The exciting part is what the fleet does, not how it's wired. That's the whole point of a socket standard.

← ALL FIELD NOTES