Wiring MCP Tools Into Claude: Auth, Schemas, Errors

The gap between an MCP server that works in a demo and one you can put in front of production is almost entirely about the unglamorous parts: who is allowed to call it, what shape the arguments must take, what happens when the upstream system is down, and what happens when Claude retries a write. Get these right and an agent is a dependable colleague. Get them wrong and you have built a fast, confident way to corrupt data. This post is about wiring tools in correctly — the auth, schemas, error handling, and idempotency that separate a toy from infrastructure.

We will go boundary by boundary, because that is where production agents succeed or fail. The model's reasoning is rarely the problem; the seams are.

Authentication: the server holds the keys, never the model

The foundational rule is that Claude never sees a credential. The MCP server holds its own secrets and decides, per call, whether an action is permitted. For a local stdio server, that means reading credentials from the environment Claude Code launched it in. For a remote HTTP server, it means validating a bearer token or OAuth flow on every request and scoping what the caller can do.

// Remote server: authenticate every request
app.use((req, res, next) => {
  const token = req.headers.authorization?.split(" ")[1];
  const principal = verifyToken(token);     // throws if invalid
  if (!principal) return res.status(401).end();
  req.principal = principal;                 // scope downstream
  next();
});

Crucially, authorization is per-tool, not per-server. A reporting agent might be allowed get_orders but not refund_order. Enforce that in the server based on the authenticated principal — do not rely on the Skill to politely avoid calling a dangerous tool. The model is a co-pilot, not a security boundary.

Schemas: the contract Claude actually reads

A tool's input schema is doing double duty. It validates arguments, and it teaches Claude how to call the tool. Both jobs reward precision. Use a typed schema with descriptions on every field, constrain enums rather than accepting free strings, and mark required versus optional explicitly.

{ orderId: z.string().regex(/^ORD-\d+$/).describe("Order id like ORD-4823"),
  reason: z.enum(["defective","late","duplicate"]).describe("Refund reason"),
  amountCents: z.number().int().positive().max(50000)
    .describe("Refund amount in cents, max $500") }

That max(50000) is not just validation; it is a guardrail the server enforces no matter what the model proposes. The enum means Claude cannot invent a novel reason. Tight schemas turn "hope the model behaves" into "the server won't let it misbehave." Every constraint you can express in the schema is one you don't have to police in prose.

flowchart TD
  A["Claude proposes tool call"] --> B["MCP client forwards to server"]
  B --> C{"Auth valid & tool allowed?"}
  C -->|No| D["Return 401/403 typed error"]
  C -->|Yes| E{"Args pass schema?"}
  E -->|No| F["Return VALIDATION_ERROR + hint"]
  E -->|Yes| G{"Idempotency key seen?"}
  G -->|Yes| H["Return prior result"]
  G -->|No| I["Execute & record key"]
  I --> J["Return structured result"]

Error handling: fail in shapes the model can use

When something goes wrong, the difference between a stack trace and a typed error is the difference between an agent that flails and one that recovers. Return a stable code, a human-readable message, and any data the model needs to choose a next step.

return { isError: true, content: [{ type: "text", text: JSON.stringify({
  error: "RATE_LIMITED", retryAfterMs: 2000,
  message: "Upstream throttled; retry after the given delay."
}) }] };

With this, your Skill can instruct: "On RATE_LIMITED, wait retryAfterMs and retry once; on VALIDATION_ERROR, fix the argument the hint names; on anything unrecognized, stop and report." Deterministic branching on stable codes is what makes long agentic runs survivable. Distinguish clearly between errors the model should retry (transient: timeouts, throttling), errors it should fix (validation), and errors it must surface to a human (auth, policy). Encode that distinction in the code itself so the Skill never has to guess.

Idempotency: assume every write will be retried

Agents retry on timeouts, on ambiguous responses, sometimes on a model's own second-guessing. Any tool with a side effect must therefore be idempotent. Accept a client-supplied key, record it the first time you act, and on any repeat with the same key return the original result without re-executing.

async function issueRefundOnce({ idempotencyKey, ...args }) {
  const seen = await store.get(idempotencyKey);
  if (seen) return seen;                 // safe replay
  const result = await issueRefund(args);
  await store.put(idempotencyKey, result);
  return result;
}

Pair this with a Skill instruction to derive the key deterministically — say, a hash of the order id and reason — so a genuine retry reuses the key while a legitimately new request gets a fresh one. Without idempotency, a flaky network turns one refund into two; with it, retries are free and safe. This is the single most important habit for any tool that changes state.

Timeouts and circuit breakers at the boundary

Finally, protect the agent from slow dependencies. Wrap upstream calls in a timeout and return a typed UPSTREAM_TIMEOUT rather than hanging. If a dependency is failing repeatedly, a simple circuit breaker that fast-fails with a clear code keeps the agent from spending its turn budget waiting. The model can then choose a degraded path the Skill defines — say, queue the action for later — instead of stalling. Resilience lives at the seam between the server and the systems behind it, and the model can only be as reliable as the worst-handled boundary.

Frequently asked questions

Should the model ever receive raw credentials to pass to a tool?

No. Credentials belong to the server's environment or its auth layer, never in the model's context or tool arguments. If a tool seems to need a secret as input, redesign it so the server resolves the secret itself based on the authenticated caller.

How do I stop Claude from calling a destructive tool it shouldn't?

Enforce authorization in the server based on the authenticated principal, and gate destructive variants behind a required confirmation flag the server checks. Skill guidance helps, but the server must be the real boundary — never trust the model alone to abstain.

What's the right retry policy for transient tool errors?

Return a typed transient code with a suggested delay, and have the Skill retry a bounded number of times with backoff before surfacing the failure. Cap retries explicitly so a persistently failing dependency can't consume the whole run.

Bringing agentic AI to your phone lines

CallSphere wires these same safeguards — per-tool auth, typed schemas, idempotent writes — into voice and chat agents that answer every call and message, act through tools mid-conversation, and book work 24/7. 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.