Wiring MCP Servers into Claude Agents: Auth and Idempotency

The tool that lists invoices is easy. The tool that issues a refund is where managed agents get dangerous, because now a dropped connection, a retry, or a confused model can move money twice. Wiring MCP servers into a Claude agent correctly is mostly about the unglamorous parts: how the server authenticates the caller, how schemas keep bad calls out, how errors come back as something the agent can use, and how you guarantee that running a tool twice does the same thing as running it once. This post is about getting those four things right.

Key takeaways

• Authenticate the tunnel session once at connection time; per-call auth should ride that established identity, not re-prompt.
• Strict JSON schemas are your first line of defense — reject malformed calls before any handler runs.
• Return errors as typed, coded results with hints so the agent can recover instead of looping.
• Make every mutating tool idempotent with a client-supplied key so retries after a dropped tunnel are safe.
• Scope credentials per tool and per run so the blast radius of any single tool is small and auditable.

Authentication: establish identity at the tunnel, scope at the tool

MCP authentication in a managed-agent setup happens at two levels, and conflating them causes pain. The first level is the tunnel session: when the sandbox dials the control plane, it authenticates once with a session token, establishing who this sandbox is and which agent run it belongs to. Every tool call inside that session inherits that identity — you do not re-authenticate per call, which would add latency and complexity for no benefit.

The second level is authorization inside each tool. The session says "this is acme's sandbox"; the tool enforces "and acme may only touch acme's invoices." Bake the org scope into the credentials the tool uses, not into something the model can pass. If the agent could supply an org_id argument, a prompt injection could supply a different one. Keep the scope server-side and immutable for the run.

Schemas as the first line of defense

Before any of your code runs, the schema decides whether a call is even valid. This is where you catch the majority of agent mistakes cheaply. Require every field that matters, forbid extras, and constrain formats. A refund tool that demands a positive integer amount and a known currency will simply reject a malformed call with a clear error the agent can read.

{
  "name": "refund_payment",
  "input_schema": {
    "type": "object",
    "properties": {
      "payment_id": { "type": "string", "pattern": "^pay_[a-z0-9]+$" },
      "amount_cents": { "type": "integer", "minimum": 1 },
      "idempotency_key": { "type": "string", "minLength": 8 }
    },
    "required": ["payment_id", "amount_cents", "idempotency_key"],
    "additionalProperties": false
  }
}

Notice the idempotency_key is part of the schema and required. That single design choice is what makes the next section possible — the agent must supply one, so retries always carry it.

Idempotency: surviving the retry you cannot avoid

The tunnel is stateful and will occasionally drop. When it does, an in-flight tool call has an uncertain fate — maybe it ran, maybe it did not. The only safe response is to retry, and the only safe retry is an idempotent one. An idempotent tool produces the same effect whether it runs once or five times with the same inputs.

flowchart TD
  A["Agent calls refund_payment"] --> B["Server reads idempotency_key"]
  B --> C{"Key seen before?"}
  C -->|Yes| D["Return stored prior result"]
  C -->|No| E["Execute refund once"]
  E --> F["Store key + result"]
  F --> G["Return result over tunnel"]
  D --> G

The implementation is a keyed record: on each call, look up the idempotency key; if you have seen it, return the stored result without re-executing; if not, execute, store the result against the key, then return it. Now a retry after a dropped tunnel is harmless — the second attempt finds the key and replays the original outcome instead of issuing a second refund.

Two details make or break this in production. First, the store-and-execute step must be atomic, or two near-simultaneous retries can both miss the key and both execute. A unique constraint on the key in your datastore gives you this for free: the second insert fails, and you treat that failure as "already processed." Second, decide how long keys live. A key retained forever is a slow leak; one expired too soon reopens the double-execution window. A retention window comfortably longer than any plausible retry — hours, not seconds — is the safe default for money-moving tools.

Error handling the agent can actually use

An error that reaches the model as a raw exception usually causes a loop: the agent does not know what to change, so it tries the same thing again. Errors that reach the model as structured data cause recovery. Return a stable code, a clear reason, and where possible a hint about the next action.

{ "error": "payment_not_refundable",
  "reason": "payment is older than 90 days",
  "hint": "offer store credit via issue_credit instead" }

This shape gives the agent a path forward. It reads payment_not_refundable, sees the hint, and pivots to issue_credit on the next turn. The difference between this and a stack trace is the difference between an agent that resolves the task and one that burns ten turns retrying a dead end.

Scope credentials per tool, per run

Each tool should hold the narrowest credential that lets it do its job, and those credentials should be minted for the run, not shared globally. A read tool gets a read-only key; the refund tool gets a key that can refund but not, say, delete accounts. When credentials are scoped this tightly, the worst case for any single compromised or misused tool is bounded by that tool's permissions. Auditing the agent becomes auditing a small matrix of tools against their grants.

Per-run scoping adds another layer: because the sandbox is ephemeral and its credentials expire with it, a leaked key from one run is useless in the next. This pairs naturally with the per-run sandbox model — short-lived environments with short-lived, narrow credentials.

One more habit pays off here: log every tool call with its arguments, its idempotency key, and its result code, keyed to the run id. Managed agents act on your behalf, and when something goes wrong — a refund that should not have happened, a record changed unexpectedly — the first question is always "what exactly did the agent do?" A per-run audit trail answers that in seconds instead of forcing you to reconstruct intent from model output. It also gives you the raw material to spot patterns, like a tool the agent keeps misusing, that point you back to a schema or description that needs tightening.

Wire an MCP tool safely in 6 steps

1. Authenticate the tunnel session once; do not re-auth per call.
2. Write a strict schema with required, format patterns, and additionalProperties: false.
3. Make the org/tenant scope server-side and immutable — never a model-supplied argument.
4. Require an idempotency key for any mutating tool and key your effects on it.
5. Return errors as coded objects with a reason and a recovery hint.
6. Mint a narrow, run-scoped credential for the tool and let it expire with the sandbox.

Auth and reliability choices

Concern	Fragile approach	Robust approach
Auth	Re-auth every call	Session at tunnel, scope in tool
Tenant scope	Model passes org_id	Server-side, immutable
Retries	Hope nothing dropped	Idempotency key replay
Errors	Raw exception	Coded result + hint
Credentials	One global key	Narrow, per-run, expiring

Frequently asked questions

Should the agent pass an org or tenant id as a tool argument?

No. Tenant scope must be server-side and immutable for the run, baked into the credentials the tool uses. If the model could supply it, a prompt injection could change it and cross tenant boundaries.

What makes a tool idempotent in this context?

The tool requires a client-supplied idempotency key, records the result against that key on first execution, and replays the stored result on any repeat. Running it again with the same key produces no additional effect.

Why return errors as structured objects?

A coded error with a reason and hint lets the agent recover and pick a different action on the next turn. A raw exception gives it nothing to act on, so it tends to loop and waste turns.

How often does the tunnel actually drop?

Rarely, but on long runs it is inevitable, and a single drop during a money-moving call is enough to justify idempotency. Design for the retry you cannot prevent rather than hoping it never happens.

Bringing agentic AI to your phone lines

CallSphere wires authenticated, idempotent tools into voice and chat agents that answer every call, take real action mid-conversation, and book work 24/7 without double-charging anyone. See it at callsphere.ai.

---

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.