Wiring tools and MCP servers into Agent Skills safely

A skill that only writes text is easy. The moment a skill calls a real tool — hits an API, mutates a database, sends a message — the failure surface explodes. Now you have authentication, malformed arguments, partial failures, retries, and the very real possibility of doing the same dangerous thing twice. This is where most Agent Skills quietly break in production, and it's also where the gap between a demo and a dependable system is widest. This post is about wiring tools and MCP servers into skills correctly, and how to test that wiring with skill-creator so the failures show up in evals instead of on call.

The Model Context Protocol is an open standard, introduced in late 2024, that connects Claude to external tools and data through MCP servers; Agent Skills pair with it by teaching Claude when and how to use those tools. Getting that pairing right is four concerns — auth, schemas, error handling, and idempotency — and each one is testable.

Key takeaways

• Schemas are your first line of defense: tight JSON schemas stop malformed tool calls before they leave the model.
• Auth lives outside the skill: the MCP server holds credentials; the skill never sees secrets, which keeps them out of context and logs.
• Every tool can fail: design the skill to read tool errors and recover, not assume success.
• Mutations must be idempotent: an idempotency key turns an accidental double-call into a no-op instead of a duplicate.
• Test the wiring, not just the prose: skill-creator scenarios should include error and retry paths, not only happy paths.

Where the skill ends and the server begins

The cleanest mental model is a hard boundary. The MCP server owns the connection to the outside world: the credentials, the network calls, the rate limits, the retries against the upstream API. The skill owns the decision — when to call which tool, with what arguments, and what to do with the result. Keeping this boundary sharp means the skill's body never contains an API key, a token, or a raw endpoint, and that is both a security property and a context-hygiene property.

In practice this means the skill body reads like "when the user confirms the booking, call the create_booking tool with the validated payload," and the server is what actually authenticates and posts. If you find yourself writing auth logic into a skill, that logic is in the wrong place.

Schemas: stop bad calls before they happen

The JSON schema on a tool is not documentation, it is enforcement. A precise schema — required fields, enums for constrained values, formats for dates and emails, sensible bounds — means many malformed calls are rejected structurally before any side effect occurs. Loose schemas push that validation into prose the model may or may not honor, which is exactly the kind of thing that passes in a demo and fails under variance.

{
  "name": "create_booking",
  "input_schema": {
    "type": "object",
    "required": ["service", "start_iso", "customer_email"],
    "properties": {
      "service": { "type": "string", "enum": ["cleaning", "repair", "inspection"] },
      "start_iso": { "type": "string", "format": "date-time" },
      "customer_email": { "type": "string", "format": "email" },
      "idempotency_key": { "type": "string" }
    }
  }
}

The enum makes an invalid service impossible to submit, and the explicit idempotency_key sets up the safety we'll use below. Notice the schema does work the skill body no longer has to describe in fragile sentences.

The call lifecycle, including the unhappy paths

The flow that matters is not the happy path — it's what happens when the call fails. A well-wired skill treats every tool result as something to inspect, not assume.

flowchart TD
  A["Skill decides to call tool"] --> B["Validate args vs schema"]
  B -->|Invalid| C["Fix args, no side effect"]
  B -->|Valid| D["MCP server authenticates & calls API"]
  D --> E{"Result?"}
  E -->|Success| F["Use structured data"]
  E -->|Transient error| G["Retry with same idempotency key"]
  E -->|Hard error| H["Surface clear message to user"]
  G --> D

The retry edge is the subtle one. A transient failure — a timeout, a 503 — should be retried, but only safely. If the first attempt actually succeeded upstream before the connection dropped, a naive retry creates a duplicate booking. That is precisely what the idempotency key prevents, which is why it belongs in the schema from the start.

Auth without leaking secrets

Authentication should be invisible to the skill. The MCP server holds the OAuth token or API key, refreshes it, and attaches it to outbound requests; the skill simply calls the tool. This keeps credentials out of the model's context window — where they could be echoed into a transcript or a log — and centralizes rotation. When a token expires, you fix it in one place, not in every skill that touches the service.

A practical rule: if a secret value ever appears in SKILL.md or in a tool argument the model fills in, treat it as a bug. The model should pass identifiers and payloads, never credentials.

Idempotency: the difference between a glitch and an incident

Mutating tools — anything that creates, charges, or sends — need idempotency, because in an agentic loop a call can be repeated by a retry, a re-plan, or a model that didn't register the first success. The pattern is to attach a stable key derived from the intent (for a booking: customer, service, and slot), so the server can recognize a repeat and return the original result instead of performing the action again. Read-only tools don't need this; every write does.

Generate the key from the request's semantic content, not a random value, so two attempts at the same action collide and two genuinely different actions don't. This single discipline converts the scariest class of agent bug — silent duplication of real-world effects — into a harmless no-op.

Testing the wiring with skill-creator

Most skill eval sets only test the happy path, which is exactly why tool-wiring bugs reach production. Your scenarios should deliberately exercise the failure edges: a prompt that would produce an invalid argument (does the schema catch it?), a simulated transient error (does the skill retry safely?), and a repeated request (does idempotency hold?). Because skill-creator runs each scenario multiple times, it's well suited to surfacing the intermittent, retry-related bugs that single runs miss.

Common pitfalls

• Loose schemas: free-text where an enum belongs lets the model invent invalid values that only fail at the API.
• Assuming tools succeed: a skill that ignores error results will happily build a final answer on top of a failed call.
• Random idempotency keys: a fresh key per attempt defeats the entire purpose; derive it from the action's content.
• Secrets in arguments or the body: credentials in context leak into transcripts and logs and break rotation.
• Happy-path-only evals: if no scenario fails a tool on purpose, you have never actually tested your error handling.

Wire a tool into a skill in five steps

1. Define the tool with a strict JSON schema — required fields, enums, formats, and an idempotency key for mutations.
2. Put auth in the MCP server; verify no secret ever enters the skill body or arguments.
3. Write the skill body to inspect each tool result and branch on success, transient error, and hard error.
4. Derive idempotency keys from request content so retries collapse and distinct actions don't.
5. Add skill-creator scenarios for bad args, injected errors, and repeated calls; run with samples and confirm safe behavior.

Frequently asked questions

What is the Model Context Protocol?

The Model Context Protocol is an open standard, introduced in late 2024, that connects Claude to external tools and data through MCP servers. Agent Skills complement it by teaching Claude when and how to use those connected tools.

Why keep authentication in the MCP server instead of the skill?

So credentials never enter the model's context, where they could surface in a transcript or log, and so token rotation happens in one place. The skill passes payloads and identifiers; the server holds the secrets.

When does a tool need an idempotency key?

Whenever it mutates state — creates, charges, or sends. In an agentic loop a call can be repeated by a retry or re-plan, and a content-derived key lets the server turn a duplicate attempt into a safe no-op.

Bringing agentic AI to your phone lines

CallSphere wires these same tool-and-MCP patterns into voice and chat agents that answer every call and message, call real tools mid-conversation — booking, lookups, payments — and run safely 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.