Wiring MCP Servers into Claude: Auth, Schemas, Errors

Connecting Claude to a single hand-written function is easy. Connecting it to a fleet of external systems — a ticketing platform, a Git host, an internal API — through Model Context Protocol is where the real engineering lives. The happy path takes ten minutes; the parts that take ten days are authentication, schema design, error recovery, and idempotency. This post is about those parts: the unglamorous wiring that decides whether your MCP integration survives contact with production.

What MCP actually moves around

Model Context Protocol is an open standard that connects Claude to external tools and data through MCP servers, which advertise their tools, prompts, and resources over a defined transport. When you wire a server in, the SDK lists its tools and converts each into an Anthropic tool definition the model can call. From the agentic loop's point of view, an MCP tool is indistinguishable from a local one — the difference is entirely in how the call is routed and authenticated.

There are two ways to consume MCP in the Claude API. You can let the model connect to a remote MCP server directly via an mcp_servers parameter, or you can run a local MCP client and use the SDK's conversion helpers to feed the server's tools into the tool runner. The local-client path gives you more control over the connection — which matters precisely when auth and error handling get hard.

flowchart TD
  A["Model emits tool_use"] --> B["Router: local or MCP?"]
  B -->|MCP| C["Attach auth token"]
  C --> D["Call MCP server"]
  D --> E{"Server response"}
  E -->|2xx| F["Return structured tool_result"]
  E -->|auth error| G["Refresh token, retry once"]
  E -->|other error| H["tool_result is_error=true"]
  G --> D
  F --> A
  H --> A

Auth: keep credentials out of the model's reach

The cardinal rule of MCP auth is that credentials never enter the prompt. Putting an API key in the system prompt or a user message is a durable leak — it persists in conversation history, gets returned by event listings, and can be summarized into compaction blocks. The correct pattern injects the credential at the transport layer, after the tool call leaves the model's context.

Hosted MCP servers typically authenticate with OAuth bearer tokens, not the service's native API key — a common trap. A Notion integration token works against Notion's REST API but will not authenticate the Notion MCP server. When you store credentials, store the access token plus a refresh token, and let your client refresh on expiry. In managed setups, vaults hold these credentials and an Anthropic-side proxy injects them; in self-hosted setups, your client owns the refresh logic. Either way the design goal is identical: the model orchestrates, your infrastructure authenticates.

Schemas: precise, closed, and example-rich

An MCP tool's schema is the contract the model fills in, and loose schemas produce loose calls. Three rules pay off repeatedly. First, set additionalProperties: false and list required fields explicitly, so the model can't invent parameters. Second, use enum for any field with a fixed value set — it eliminates an entire class of typo'd arguments. Third, when a server exposes a tool with a complex shape, add a sample call in the definition so the model has a concrete pattern to mimic.

One operational subtlety: recent Claude models may escape Unicode or forward slashes in tool-call input differently than older ones. Always parse arguments with a real JSON parser — never string-match the serialized input. A handler that does if input == '{"path":"/x"}' will silently break the day the model escapes that slash. Treat block.input as the parsed object the SDK gives you and validate it structurally.

Error handling: failures are messages, not exceptions

The defining move of robust agent integration is treating a tool failure as data the model can act on, not an exception that kills the loop. When an MCP call fails, return a tool_result with is_error: true and an informative message — "Ticket TICK-9 not found; verify the ID" — and the model will adjust, ask for clarification, or try a different tool. Throw instead, and the agent dies on the first transient hiccup.

results.append({
    "type": "tool_result",
    "tool_use_id": call.id,
    "content": "Error: rate limited by upstream. Retry in 30s.",
    "is_error": True,
})

Layer your retries deliberately. Transport-level errors — a 429 or 5xx from the MCP server — deserve an automatic retry with backoff inside your client, invisible to the model. Semantic errors — a missing record, an invalid argument — should surface to the model as an error tool_result so it can reason about them. The split keeps the model focused on the task while your infrastructure absorbs the noise. Large MCP outputs are worth special handling too: when a tool returns a huge payload, offload it to a file and hand the model a preview plus a path rather than flooding the context window.

Idempotency: the loop will retry, so plan for it

Agentic loops retry. A dropped connection, a pause_turn continuation, or a reconnect after a stream drop can all cause the same tool call to fire twice. For read-only tools this is harmless. For side-effecting ones — charge a card, send an email, create a ticket — a double-fire is a bug that bites in production and never in testing.

The fix is idempotency keys. Have the tool derive a deterministic key from its arguments (or accept one) and make the underlying operation a no-op on repeat. A create_ticket tool that includes a client-generated request ID, and a backend that deduplicates on that ID, turns a dangerous double-fire into a harmless one. Pair this with confirmation gates on the most destructive actions — promote them to dedicated tools so your harness can require human approval before the call runs at all.

Putting it together with the tool runner

With auth, schemas, errors, and idempotency handled, the actual wiring is short. You initialize an MCP client session, list its tools, convert them, and hand them to the runner alongside your local tools. The runner drives the loop; your conversion layer and credential injection do the rest. The lesson worth carrying away is that the model-facing surface stays simple precisely because the engineering went into the four layers underneath it.

Frequently asked questions

Can Claude connect to a remote MCP server without any local code?

Yes — the Messages API accepts an mcp_servers parameter that lets the model connect directly. Use the local-client conversion helpers instead when you need tighter control over auth, retries, or the connection lifecycle, which is usually the case in production.

Why does my MCP server reject the token even though it's valid?

Most hosted MCP servers want an OAuth bearer token, not the service's native API key. They're different auth systems. A service-native token authenticates the REST API but not the MCP endpoint — obtain an OAuth credential and store its refresh token so it can be renewed.

How do I keep a retried tool call from charging a customer twice?

Use idempotency keys. Derive a deterministic key from the call arguments and make the side-effecting operation a no-op on repeat. The agentic loop can and will retry, so design every non-idempotent tool to tolerate being called twice with the same input.

What happens when an MCP tool returns a massive result?

Don't let it flood the context. Offload large outputs to a file and return a truncated preview plus the file path, so the model can choose to read the full content only if it needs to. Many managed setups do this automatically above a token threshold.

Bringing agentic AI to your phone lines

CallSphere wires these same integration disciplines — authenticated tool calls, error-as-data recovery, idempotent side effects — into voice and chat agents that reach into your real systems mid-conversation to check availability, create records, and book work. See reliable tool-wiring on a live call 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.