Wiring MCP Tools into Claude: Auth and Error Handling

The gap between a Claude agent that demos well and one that survives in production is almost entirely in the plumbing between the model and your real systems. A tool that works on the happy path will, at enterprise scale, eventually be called with bad input, against an expired token, during a partial outage, or twice in a row because the model retried. Model Context Protocol gives you a clean standard for exposing tools — but the standard does not decide your auth model, your error contracts, or your idempotency strategy. Those are yours to get right. This post is about getting them right.

Key takeaways

• Treat the MCP server as a real API boundary — authenticate, authorize, and validate every call, not just the demo ones.
• Return errors as structured, model-readable messages so Claude can recover instead of hallucinating.
• Make every state-changing tool idempotent with a client-supplied key, because agents retry.
• Scope credentials per agent and per user; never hand one tool a god-mode token.
• Validate inputs against the schema server-side — the schema guides the model but does not bind it.

Auth: the server is a boundary, not a helper

It is tempting to think of an MCP server as an internal convenience that runs alongside your agent. In production it is a security boundary that an autonomous system calls on a user's behalf. That framing forces the right questions. Who is this call for — which end user? What is this agent allowed to do? Is the credential it presents still valid? A robust pattern is per-request authorization: the host passes a short-lived token tied to the acting user, the server verifies it, and the server enforces that user's permissions before touching any backend.

Avoid the anti-pattern of a single broad service credential shared by every tool. If the agent only needs to read orders for the current customer, the credential it carries should permit exactly that. Scoped, short-lived tokens mean a confused or compromised agent has a small blast radius. Centralizing this in the MCP server — rather than in each agent — is one of the strongest arguments for MCP in the first place.

Error handling Claude can actually use

When a tool fails, how it fails determines whether the agent recovers gracefully or spins into nonsense. A raw stack trace or an opaque HTTP 500 gives the model nothing to work with. A structured error — a clear type and a human-readable message — lets Claude reason about next steps: retry, ask the user for a corrected value, or report the failure honestly.

// Tool result on failure — readable by the model
{
  "error": {
    "type": "not_found",
    "message": "No order matches ID 'INV-99'. Confirm the ID format (INV-YYYY-NNNNN).",
    "retryable": false
  }
}

The retryable flag is doing useful work: it tells the agent whether trying again could help. For a transient timeout you would set it true; for a validation failure, false. Encode this contract once and every tool benefits. The diagram below shows the full path of a single tool call including the branches most teams forget to handle.

flowchart TD
  A["Claude requests tool call"] --> B["MCP server: authenticate token"]
  B --> C{"Authorized & valid?"}
  C -->|No| D["Return auth error to model"]
  C -->|Yes| E["Validate input vs schema"]
  E --> F{"Idempotency key seen?"}
  F -->|Yes| G["Return cached prior result"]
  F -->|No| H["Execute & persist result"]
  H --> I["Return structured result"]
  D --> I
  G --> I

Idempotency: agents retry, so plan for it

A human clicks a button once. An agent in a loop may call issue_refund, get a timeout before the response arrives, and call it again — having no way to know the first call actually succeeded. Without protection, the customer gets refunded twice. The fix is the same one mature payment APIs use: idempotency keys. The agent (or host) supplies a unique key per logical operation; the server records the key with the result and, on any repeat with the same key, returns the stored result instead of re-executing.

async function issueRefund({ order_id, amount, idempotency_key }) {
  const prior = await store.get(idempotency_key);
  if (prior) return prior;                 // safe replay
  const result = await payments.refund(order_id, amount);
  await store.put(idempotency_key, result); // persist before returning
  return result;
}

The ordering matters: persist the result under the key before you return it, so a crash between execution and storage does not lose the record. With this in place, an agent retry is harmless — exactly the property you need when a non-deterministic model is driving.

Schemas are a contract you must version

The JSON schemas you attach to tools are not write-once artifacts. As your backend evolves, fields get added, renamed, or deprecated — and an agent already running against the old shape will break in confusing ways if you change a tool out from under it. Treat tool schemas like any other public API contract: version them, deprecate gracefully, and avoid changing the meaning of an existing field. If a tool needs a genuinely different shape, it is usually safer to introduce a new tool name than to silently mutate the old one, because the model has learned to call the old one a certain way.

Descriptions deserve the same care. Because Claude chooses tools largely from their descriptions, a sloppy edit to a description is effectively a behavior change. When you tighten a description to fix a mis-call, re-run your eval set — the same change that stops one wrong call can suppress a correct one elsewhere. The discipline here mirrors backend engineering exactly: schemas and descriptions are the interface, the interface is load-bearing, and load-bearing things get reviewed and tested before they ship.

Validate server-side, always

The JSON input schema you attach to a tool guides the model toward well-formed calls, and most of the time the model complies. But the schema is advisory at the model layer — it does not guarantee the input. The server must validate independently: required fields present, types correct, values within allowed ranges, IDs matching expected formats. A rejected call should come back as a structured validation error the model can fix, not a crash. Treat the schema as documentation for Claude and a separate validator as the real gatekeeper.

Tool design choices that prevent failures

Decision	Fragile choice	Robust choice
Credentials	Shared service token	Per-user short-lived token
Errors	Raw exception / 500	Typed, retryable-flagged result
Writes	Fire and forget	Idempotency key + replay
Input	Trust the schema	Re-validate server-side
Scope	One broad tool	Narrow, least-privilege tools

Common pitfalls

• Sharing one credential across all tools. A single broad token turns any tool error into a maximum-blast-radius incident. Scope per user and per capability.
• Leaking raw errors to the model. Stack traces confuse the agent and may leak internals. Map failures to a small set of typed, safe error shapes.
• Non-idempotent writes. The first timeout you hit in production will double-charge or double-send. Add idempotency keys before launch, not after.
• Trusting schema validation alone. The model usually follows the schema but is not bound by it; validate every field server-side.
• No timeouts on backend calls. A hung dependency turns into a hung agent. Bound every outbound call and surface a retryable timeout.

Harden your MCP tools in 6 steps

1. Require a short-lived, user-scoped token on every tool call and verify it server-side.
2. Define a small set of typed error shapes with a retryable flag and use them everywhere.
3. Add idempotency keys to every state-changing tool and persist results before returning.
4. Re-validate all inputs against the schema in the server, returning structured validation errors.
5. Set timeouts and least-privilege scopes on every backend dependency.
6. Log each call's identity, input, outcome, and latency for audit and debugging.

Frequently asked questions

Does MCP handle authentication for me?

MCP standardizes how tools are exposed and called, but you implement authentication and authorization in your server. The protocol gives you the transport and the call shape; the trust decisions are yours, which is exactly why you should treat the server as a real API boundary.

Where should idempotency keys come from?

Generate them at the point where a logical operation begins — typically the host or agent harness — so a retried call carries the same key. The server stores the key with its result and replays that result on any duplicate.

How should the agent react to a tool error?

That depends on your error contract. With a typed result and a retryable flag, Claude can retry transient failures, ask the user to correct a bad value, or report a hard failure honestly — instead of guessing, which is what raw errors invite.

Bringing agentic AI to your phone lines

CallSphere wires authenticated, idempotent MCP tools into voice and chat agents so a call can safely trigger real actions — bookings, lookups, updates — without double-processing. See the wiring at work on 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.