Wiring MCP tools into Claude: auth, schemas, and errors

The demo version of connecting a tool to Claude is easy: expose a function, watch the model call it, applaud. The production version is where the real work lives — what happens when the auth token expires mid-task, when the model passes a malformed argument, when a network blip causes the same charge to fire twice. Wiring MCP servers into a Claude agent so they hold up under load is mostly about the unglamorous concerns: authentication, schema discipline, error handling, and idempotency. Get those right and your agent is trustworthy; skip them and it is a liability with a friendly interface.

What MCP actually gives you, and what it doesn't

The Model Context Protocol is an open standard, introduced by Anthropic in November 2024, that lets external servers expose tools, resources, and prompts to an AI client like Claude over a uniform interface. What MCP standardizes is the wire format and the discovery mechanism — how tools are advertised and invoked. What it deliberately leaves to you is the hard part: how those tools authenticate, how strictly they validate input, and how safely they handle repeated or failed calls. MCP is the socket; the reliability is the appliance you plug into it.

This division is a feature, not a gap. Because MCP doesn't dictate your auth or error semantics, you can wrap existing internal services without contorting them. But it means a working MCP connection is the start of the job, not the end. The server that compiles and responds is not the same as the server you would trust to issue refunds in production.

Authentication: scope the agent, not just the connection

The first question for any MCP server is what identity the agent acts as. The wrong answer is a single god-credential that can do everything; the right answer is a scoped credential that grants exactly the permissions the agent's tools require and nothing more. If your agent only reads orders and drafts replies, its credential should be incapable of issuing refunds, no matter what the model decides to attempt. You are constraining the blast radius at the auth layer, below the model's reach.

flowchart TD
  A["Claude requests tool call"] --> B["MCP server receives request"]
  B --> C{"Auth token valid & scoped?"}
  C -->|No| D["Return auth error to model"]
  C -->|Yes| E{"Input matches schema?"}
  E -->|No| F["Return validation error"]
  E -->|Yes| G{"Idempotency key seen?"}
  G -->|Yes| H["Return cached result"]
  G -->|No| I["Execute & persist result"]

Handle token lifecycle explicitly. Tokens expire, and a long-running agent will hit that boundary mid-task. The server should detect an expired or invalid token and return a clear, structured error — not a stack trace — so the agent loop can surface it cleanly and the orchestration layer can refresh and retry. Treat auth failures as a normal, expected branch of execution, because in a long session they are.

Schemas: the model's contract and your first line of defense

Every MCP tool advertises a JSON schema for its inputs, and that schema does double duty. For the model, it is instruction — it shapes what arguments the model constructs. For your server, it is the first validation gate. Make schemas as strict as the domain allows: enumerate valid values rather than accepting free strings, mark required fields required, set bounds on numbers. A tight schema steers the model toward correct calls and rejects the malformed ones before they reach your business logic.

But never let the schema be your only check. Schema validation confirms shape, not meaning — it cannot know that an order id belongs to this customer or that an amount is within policy. Validate semantics inside the tool and return precise errors when a call is well-formed but invalid: "order 1234 belongs to a different account." The model reads that and corrects course. Vague errors like "invalid request" leave it guessing; specific errors let it self-repair, which is the whole point of returning errors as data.

Error handling: return failures the model can reason about

The cardinal rule of MCP error handling is that errors are data, not exceptions. When a tool fails, return a structured result describing what went wrong and, where possible, what to do about it. There is a meaningful difference between "transient: database timeout, safe to retry" and "permanent: account closed, do not retry," and encoding that distinction lets the agent respond correctly — retrying the first, abandoning the second. A model handed a clear failure mode behaves remarkably sensibly; a model handed a raw exception or a crashed connection cannot.

Distinguish the layers of failure, too. Transport errors, auth errors, validation errors, and business-logic errors are different categories, and the agent benefits from knowing which it hit. A bare 500 forces guesswork. A response that says "validation error: email is not a valid address" tells the model exactly what to fix. Investing in error taxonomy pays for itself the first time an agent recovers from a failure that would otherwise have derailed the whole task.

Idempotency: the safeguard that makes retries safe

Agents retry. The loop is built to react to failures by trying again, which is exactly what you want for reads and exactly what can hurt you for writes. If a create_charge call times out after the charge succeeded but before the response arrives, a naive retry charges the customer twice. The fix is idempotency: every state-changing tool accepts an idempotency key, and the server records which keys it has processed. A repeated key returns the original result instead of executing again.

Make idempotency a default for writes, not an afterthought. Have the agent layer generate a stable key per logical operation and pass it through, and have the MCP server persist keys with their results so a retry — even minutes later, even after a restart — is provably safe. This single discipline is what lets you give an agent genuine write access to billing, scheduling, or inventory systems without lying awake about duplicate side effects. Without it, every retry is a gamble; with it, retries become free.

Putting it together: a server you can trust

A production-grade MCP server, in order: it authenticates with a scoped credential and fails auth cleanly; it validates input against a strict schema and then against business rules; it checks an idempotency key before any write; it executes and persists; and it returns either a structured success or a categorized, actionable error. Each layer corresponds to a branch in the flow above, and each one converts a class of silent failure into a clean signal the agent can act on. That is the difference between a tool that demos and a tool that ships.

Frequently asked questions

Does MCP handle authentication for me?

No. MCP standardizes how tools are advertised and called, but authentication, authorization, and scoping are the server's responsibility. Use a credential scoped to exactly what the agent's tools need, and treat token expiry as an expected, handled branch.

How strict should my tool schemas be?

As strict as the domain allows. Enumerate valid values, mark required fields, and bound numeric ranges. Strict schemas steer the model toward correct calls and reject malformed input early — but always back them with semantic validation inside the tool.

Why return errors instead of throwing them?

Because the agent can reason about a structured error and recover, but a crashed connection ends the loop. Returning categorized failures — transient versus permanent, with a clear reason — lets the agent retry, abandon, or correct as appropriate.

How do I make tool retries safe?

Add idempotency to every state-changing tool. Generate a stable key per logical operation, pass it with the call, and have the server return the original result for a repeated key instead of executing again. This makes the loop's natural retries safe for writes.

Bringing agentic AI to your phone lines

CallSphere wires the same MCP discipline into its voice and chat agents — scoped auth, strict schemas, structured errors, and idempotent writes — so an agent can book, reschedule, and update records mid-call without ever doubling an action. See it live 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.