Wiring MCP Servers to Claude: Auth, Schemas, Errors

The demos always show the happy path: Claude calls an MCP tool, the tool returns clean data, Claude composes a tidy answer. Production security work is the unhappy paths — an expired token mid-session, a vendor API that returns a 500 on the third call, a remediation that fires twice because a step retried, a schema that drifts and silently corrupts a compliance report. Wiring MCP servers to Claude properly means engineering for all of that. This post is about the connective tissue: auth, schemas, error handling, and idempotency, in the specific context of security and compliance tools where mistakes are expensive.

Model Context Protocol is an open standard that connects Claude to external tools and data through servers that expose typed operations and resources. That definition is simple; making it robust against real-world failure is where the engineering lives. Let us go through the four pillars in order.

Auth: scope at the source, refresh at the edge

Authentication for a security-tool MCP server has two distinct jobs that people often conflate: proving who the human session is, and proving the server's own right to call the downstream tool. Keep them separate. The downstream credential — the scanner token, the EDR API key — lives in the server's environment and should be scoped as tightly as the vendor allows. If you only need read access for a tool, the token backing that tool should be read-only, so even a server bug cannot escalate.

The session identity is what your gate and audit log key on. Carry it through the MCP request as context, resolve it to a role and scope inside the server, and reject anything that does not map to an allowed scope. For tokens that expire, build refresh into the server so a long investigative session does not die mid-flight — but make refresh failures loud and logged, never silently swallowed. The pattern to avoid at all costs is a single, broad, long-lived god-token shared across tools; that is the credential an attacker most wants and the one hardest to revoke cleanly.

flowchart TD
  A["Claude calls MCP tool"] --> B["Resolve session identity & scope"]
  B --> C{"Scope allows tool?"}
  C -->|No| D["Reject + audit"]
  C -->|Yes| E["Validate input schema"]
  E --> F{"Valid?"}
  F -->|No| G["Return typed schema error"]
  F -->|Yes| H["Check idempotency key"]
  H --> I["Call downstream tool with scoped token"]
  I --> J{"Success?"}
  J -->|Error| K["Map to structured error + audit"]
  J -->|OK| L["Normalize result + audit"]

Schemas: typed in, typed out, normalized always

A schema is a contract, and in security tooling a broken contract can mean a misfiled finding or a compliance report with the wrong evidence. Define strict input schemas for every tool — required fields, enumerated severities, validated identifiers — and reject anything that does not conform with a clear, typed error the model can understand and recover from. Loose input validation is how a vague model request becomes an unintended broad query.

Output is where the subtle work hides. Vendors return sprawling, inconsistent JSON. Your server should map every response into your own normalized types before handing it back to Claude. This normalization layer does three things at once: it gives the model a stable shape to reason over, it strips fields the model does not need (reducing both context cost and data exposure), and it isolates you from vendor changes. When the scanner reorganizes its payload, you fix one mapping function and everything downstream keeps working. Treat the normalized type, not the vendor's response, as the real interface.

Error handling: structured, recoverable, and honest

The worst thing an MCP tool can do on failure is return a raw stack trace or an empty result that the model misreads as "nothing found." Both are dangerous in security work — the first leaks internals, the second can make a real exposure look clean. The pattern is to map every failure into a small set of structured error types the model is taught to handle: a retryable transient error, a permanent client error, a permission error, and a not-found that is genuinely distinct from an error.

Distinguishing "the query succeeded and found nothing" from "the query failed" is not pedantry; it is the difference between a true and a false security conclusion. Make that distinction explicit in your return types. For transient errors, the server can retry with backoff internally before surfacing failure, but it must bound those retries and log them. And every error path writes an audit record too — a denied or failed action is exactly the kind of event a security review wants to see. Honest errors let the model reason correctly: it can retry, escalate to a human, or report a clean negative, instead of guessing.

Idempotency: make retries boring

Agents retry by nature, and a retried write against a security tool is a real incident waiting to happen. The discipline is to make every state-changing operation idempotent at the server. Accept or derive an idempotency key tied to the action's meaningful identity, record keys you have executed, and on a repeat return the prior result instead of acting again. A remediation that fires once and then deduplicates is safe; one that fires twice may double-quarantine a host or send conflicting signals to your SIEM.

Pair idempotency with clear result semantics so the model and the audit log both understand what happened. A response that says "already executed, returning prior result" is far better than silently re-running or silently doing nothing. This is also your safety net for the gate-approval flow: if an approved remediation's confirmation is retried, the idempotency check ensures the human's single approval results in exactly one action. Without it, exactly-once becomes at-least-once, and in security at-least-once is not good enough.

Putting the pillars together in one request path

The four pillars are not independent features; they are a sequence every request flows through, as the diagram above shows. Resolve identity and scope, then validate the input schema, then check idempotency, then call the downstream tool with a scoped token, then either map the error or normalize the result — and audit at every meaningful step. Implement this sequence once in a shared wrapper and every tool inherits it. That shared path is the most security-relevant code you will write, so it deserves the most tests.

When you build it this way, adding a new security tool becomes mostly a matter of declaring its schemas and its downstream call; the auth resolution, gating hook, error mapping, idempotency check, and audit writes come for free. The connective tissue, done once and done well, is what lets you scale to many tools without multiplying your risk surface. The glue is the product.

Frequently asked questions

Should each MCP tool have its own credential?

Where the vendor allows it, yes — or at least each tool should use a credential scoped to exactly what it needs. Per-tool, least-privilege credentials mean a compromise or bug in one tool cannot reach beyond its intended scope, and you can revoke one tool's access without disrupting others. A shared broad token is convenient and exactly the wrong trade-off for security work.

How should the server handle a downstream API outage?

Map it to a retryable transient error, retry a bounded number of times with backoff inside the server, and if it still fails, return a clear structured error and write an audit record. Never return an empty result that the model could mistake for a clean finding. The model should be able to tell the difference between "nothing is wrong" and "I could not check," because in security those lead to opposite actions.

Why normalize outputs instead of passing vendor JSON straight through?

Normalization gives Claude a stable shape to reason over, removes sensitive or irrelevant fields, and shields you from vendor schema changes. Passing raw JSON couples your prompts and skills to a third party's data layout, so a minor vendor release can silently break your agent. The normalized type is the interface you actually control.

Where do idempotency keys come from?

Either the server derives them from the action's meaningful identity — finding id, action type, and a time bucket — or a caller supplies one for actions where the natural identity is ambiguous. Either way the server records executed keys and short-circuits repeats. The goal is that the same intended action, however many times it is attempted, results in exactly one real effect.

Bringing agentic AI to your phone lines

CallSphere runs this same robust MCP plumbing — scoped auth, typed schemas, structured errors, idempotent writes — behind voice and chat agents that answer every call, act in your tools mid-conversation, and never double-book. 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.