Wiring Tools and MCP Servers Into Claude Agents

The first time you connect Claude to a real tool, it feels like magic. The second time — when the tool returns a vague error, or a retried call double-charges a customer, or a misconfigured server hands your agent god-mode on production data — it feels like a security incident. The gap between those two experiences is all engineering, and it lives entirely in how you wire the tools and MCP servers. This post is about that wiring: authentication, schema design, error handling, and idempotency, the four things that decide whether your agent's tool layer is an asset or a liability.

The tool boundary is a trust boundary

Start with the right mental model. When Claude decides to use a tool, it does not execute anything — it emits a structured request, a tool name plus a JSON argument object, and hands that to your runtime. Model Context Protocol is the open standard, introduced in November 2024, that lets Claude connect to external tools and data through MCP servers that expose those capabilities over one consistent interface. The crucial implication is that this is a trust boundary. The model proposes; your runtime disposes. Everything dangerous — credentials, writes, deletes, anything that costs money — sits on your side of the line, and you decide what the model is actually allowed to trigger.

Treat every MCP server as an untrusted, powerful dependency, even your own. An MCP server might expose a dozen tools; your agent probably should not be allowed to call all of them. Scoping which server tools a given agent can reach is the first and most important wiring decision, because the blast radius of an agent equals the union of the tools you handed it.

Authentication: keep secrets off the prompt

The cardinal rule of agent auth is that credentials never travel through the context window. The model should never see an API key, a database password, or a bearer token, because anything in context can end up in a log, a trace, or — with a clever prompt injection — an output. Instead, your runtime holds credentials in environment variables or a secret manager and attaches them when it executes the tool call, after the model has chosen the action but before anything runs.

For MCP servers, configure auth at the server level: the server authenticates to the downstream system using its own scoped credentials, and your agent authenticates to the server. Give each server the narrowest permissions that let it do its job — a read-only database role for a lookup server, a write-scoped token only where writes are genuinely needed. When an agent is compromised by a malicious instruction buried in retrieved data, these scoped credentials are what keep a bad afternoon from becoming a breach.

flowchart TD
  A["Claude emits tool call"] --> B{"Tool allowed for this agent?"}
  B -->|No| C["Reject, return policy error"]
  B -->|Yes| D{"Args valid vs schema?"}
  D -->|No| E["Return validation error to model"]
  D -->|Yes| F["Attach scoped credentials"]
  F --> G{"Idempotency key seen?"}
  G -->|Yes| H["Return cached result"]
  G -->|No| I["Call MCP server with timeout"]
  I --> J["Return structured result or error"]

Schema design: the description is the interface

Claude selects and fills tools almost entirely from their schemas, so the schema is the real interface — not your code. Each tool needs a name that reads like an action, a one-sentence description written for someone who cannot see the implementation, and typed parameters with their own short descriptions. "get_order_status: Look up an order by its ID and return current status, line items, and ship date" tells the model exactly when to reach for it. Vague descriptions produce vague tool selection.

Design the return schema with as much care as the inputs. Return a small, structured object containing only the fields the agent needs, and make failure states explicit: an order lookup should return {"found": false} rather than throwing, so the model can reason about the miss. Keep enums tight and validate the model's arguments against the schema before executing — never trust arguments just because they came from Claude. Validation is cheap insurance against malformed calls reaching your systems.

Error handling: failures the model can act on

The difference between a brittle and a resilient tool layer is what happens when a call fails. The pattern is to convert every failure into a structured, informative message that goes back into context, so the model can adapt rather than the loop crashing. A timeout becomes {"error": "timeout", "retryable": true}; a bad argument becomes a validation message naming the offending field; a downstream 404 becomes an explicit not-found. With this, Claude can reformulate its approach — try a different ID, fall back to another tool, or escalate — instead of failing blind.

Wrap each tool execution in its own handler with a timeout so a slow or hung MCP server cannot stall the whole loop. Distinguish retryable errors (timeouts, rate limits, transient network) from terminal ones (bad request, not found, permission denied). Cap retries and apply backoff. And crucially, never let a raw stack trace flow into the model's context — it leaks implementation details and rarely helps the model recover. Clean, structured errors are part of your prompt design whether you think of them that way or not.

Idempotency: the safeguard for every write

Agents retry. The loop reformulates, the network hiccups, a timeout fires after the server already did the work. Without idempotency, every one of these turns a single intent into duplicate side effects — two tickets, two emails, two charges. The fix is to make every write tool idempotent by accepting a client-supplied idempotency key: before executing, the server checks whether it has already processed that key, and if so returns the prior result instead of acting again.

Generate the key from the logical operation — a hash of the order ID plus the action, say — so the same intent always maps to the same key regardless of how many times the loop tries it. This one pattern eliminates an entire class of agent incidents that are brutal to debug after the fact, because by the time you notice the duplicate charge, the trace looks perfectly reasonable. Build idempotency in from the first write tool; retrofitting it after a production double-booking is a much worse week.

Discovery, versioning, and keeping the tool layer maintainable

As your agent grows, the tool layer needs lifecycle discipline. MCP makes tools discoverable — the runtime can enumerate what a server exposes — but discoverability is not the same as authorization, so keep an explicit allowlist of which tools each agent may use even as servers add capabilities. Version tool schemas the way you version an API: a changed parameter or return shape can silently alter agent behavior, so treat schema changes as breaking and replay your evals against them. Keep tool descriptions and your eval set in the same repository, so a change to one forces a look at the other. A tidy, well-scoped, well-tested tool layer is the difference between an agent you can evolve and one you are afraid to touch.

Frequently asked questions

Should I write custom tools or use an MCP server?

Use an MCP server for systems with an existing or standard integration — databases, source control, popular SaaS — so you get a maintained interface and isolation. Write custom tools for narrow, internal logic that no server covers. Many agents use both, with MCP for the heavy integrations and a few bespoke tools for glue.

How do I stop prompt injection from abusing my tools?

Scope credentials tightly, keep an allowlist of tools per agent, and never put secrets in context. Injection can make the model attempt a bad action, but if the action is not on the allowlist or the credentials cannot perform it, the damage is contained at the trust boundary.

What does an idempotency key actually look like?

A stable string derived from the logical operation — for example a hash of the entity ID plus the action and any amount. The server records keys it has processed and returns the prior result on a repeat, so retries never duplicate side effects.

How should tool errors be formatted for the model?

As small structured objects with an error type, a human-readable reason, and a retryable flag. Avoid raw stack traces; they leak internals and rarely help Claude recover. Clean errors let the model reformulate or escalate intelligently.

Tools that act on a live call

CallSphere wires tools and MCP servers into voice and chat agents with exactly this discipline — scoped auth, structured errors, idempotent writes — so the agent can check availability, update records, and book work in the middle of a real conversation. See it handling live calls 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.