Wiring MCP Servers Into Claude Cowork Safely

The moment Claude Cowork stops being a writing assistant and starts being an operational agent is the moment you wire in a tool that changes something. That's also the moment the stakes change. A connector with the wrong scope, a schema the model misreads, an error the agent silently swallows, or a write that fires twice — each is a quiet way to turn a helpful assistant into an incident. Wiring MCP servers into Cowork is mostly an exercise in getting four things right: auth, schemas, error handling, and idempotency. This post covers each with the concrete shapes you'll implement.

Key takeaways

• MCP is the boundary where every external action happens, so auth and scoping live there, not in prompts.
• Tight tool schemas with enums and required fields prevent the model from sending malformed calls.
• Return structured, actionable errors — the agent can recover from "retryable: true" but not from a stack trace.
• Make every write idempotent with a client-supplied key so retries never duplicate actions.
• Scope credentials per connector and per environment; never reuse one broad token across tools.

What MCP is doing here

The Model Context Protocol is an open standard, introduced in late 2024, that connects Claude to external tools and data through MCP servers, while skills teach the agent how to use them. In a Cowork deployment, an MCP server is the only path between the model and your systems — it exposes a set of tools, each with a schema, and it executes them against your backend. Because it is the single choke point for real-world effects, it is the right place to concentrate your engineering rigor.

That framing matters. You don't secure a Cowork agent by writing careful prose telling it not to misbehave; you secure it by exposing only the tools it should have, with schemas that constrain inputs and credentials that constrain reach. The prompt is guidance; the MCP server is enforcement.

Auth: scope narrow, per connector

Every connector should authenticate with its own credentials, scoped to exactly the operations it needs. Resist the temptation to hand one powerful service token to a connector that serves many tools — if any one tool is over-permissive, all of them are. Prefer OAuth scopes or per-tool tokens, separate credentials per environment, and short-lived tokens where the server supports them.

{
  "server": "crm-mcp",
  "auth": {
    "mode": "oauth",
    "scopes": ["contacts:read", "notes:write"],
    "token_ttl_seconds": 3600
  },
  "environment": "prod",
  "tools_allow": ["find_contact", "add_note"]
}

Here the connector can read contacts and add notes, and nothing else — it cannot delete a contact even if the server technically supports it, because that tool is neither scoped nor allow-listed. Two independent controls (scope and allow-list) guard the same boundary, which is exactly the redundancy you want at a write path.

flowchart TD
  A["Agent decides to act"] --> B["Validate args against schema"]
  B -->|Invalid| C["Return structured error"]
  B -->|Valid| D["Check idempotency key"]
  D -->|Seen before| E["Return prior result"]
  D -->|New| F["Execute against backend"]
  F -->|Success| G["Return typed result"]
  F -->|Failure| C
  C --> H{"Retryable?"}
  H -->|Yes| A
  H -->|No| I["Surface to user"]

Schemas: constrain what the model can send

A loose schema invites malformed calls. If a field is an enum, declare it as an enum; if it's required, mark it required; if it has a max, state the max. The model reads the schema and shapes its call to fit, so a tight schema is the cheapest way to prevent bad inputs before they ever reach your backend.

{
  "name": "add_note",
  "description": "Attach a note to a CRM contact.",
  "input_schema": {
    "type": "object",
    "required": ["contact_id", "body", "idempotency_key"],
    "properties": {
      "contact_id": { "type": "string" },
      "body": { "type": "string", "maxLength": 2000 },
      "visibility": { "type": "string", "enum": ["internal", "shared"] },
      "idempotency_key": { "type": "string" }
    }
  }
}

The enum on visibility means the model can't invent a third value, the maxLength caps note size, and idempotency_key is required — so every call to this write tool is, by construction, replay-safe. The schema is doing real work, not just documenting.

Error handling: make failures recoverable

When a tool fails, what it returns determines whether the agent can recover. A raw stack trace or a bare "error" leaves the model guessing. A structured error with a code, a human-readable message, and a retryable flag lets the agent do the right thing — back off and retry a transient failure, or stop and ask the user about a permanent one.

{
  "error": {
    "code": "rate_limited",
    "message": "CRM API rate limit hit; retry after 5s.",
    "retryable": true,
    "retry_after_seconds": 5
  }
}

With this shape, a rate limit becomes a brief pause instead of a failed task, while a retryable: false on an auth error tells the agent not to hammer the endpoint and to surface the problem instead. Structured errors are what separate an agent that degrades gracefully from one that loops or gives up.

Idempotency: never act twice

Agents retry. After an ambiguous timeout, the model may reasonably try the same write again — and without protection, you now have two notes, two tickets, or two refunds. The fix is a client-supplied idempotency key that the server records: if it sees the same key twice, it returns the original result instead of executing again. Require the key in the schema so it can never be forgotten, and derive it deterministically from the task so a genuine retry reuses it.

This is the single highest-leverage reliability control in the whole connector. It costs one field and a small server-side lookup, and it eliminates the most damaging failure mode in agentic systems: the silent duplicate action under load.

Common pitfalls

• One broad token for everything. A shared powerful credential makes every tool as dangerous as the most dangerous one. Scope per connector and per environment.
• Open-ended schemas. Free-string fields where an enum belongs let the model send values your backend rejects. Constrain inputs in the schema.
• Leaking raw errors. Stack traces tell the model nothing actionable. Return a code, a message, and a retryable flag.
• Optional idempotency keys. If the key is optional, it will be omitted exactly when load makes retries likely. Make it required.
• Allow-listing write tools too early. Don't surface destructive tools until a real workflow needs them and you've added review. Default to read.

Harden a connector in 5 steps

1. Give the connector its own credentials, scoped to the minimum operations, separate per environment.
2. Allow-list only the specific tools this connector should expose, excluding destructive ones by default.
3. Tighten each tool schema with required fields, enums, and length limits.
4. Return structured errors with a code, message, and retryable flag on every failure path.
5. Require a deterministic idempotency key on every write and dedupe on it server-side.

Loose vs. hardened connector

Control	Loose	Hardened
Auth	One broad token	Scoped per connector + env
Schema	Free strings	Enums, required, limits
Errors	Raw text	Code + retryable flag
Writes	No dedupe	Required idempotency key

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; skills then teach the agent how to use those tools effectively. In Cowork it is the single boundary through which all external actions pass.

Where should auth and scoping live?

At the MCP connector, not in prompts. Each connector gets its own least-privilege credentials and an explicit tool allow-list, because that boundary is what actually enforces what the agent can reach.

How should a tool report errors to the agent?

As a structured object with a code, a human-readable message, and a retryable flag (plus a retry delay when relevant). That lets the agent back off on transient failures and stop on permanent ones, instead of guessing from a stack trace.

Why require idempotency keys on writes?

Agents retry after ambiguous results, and a deterministic key lets the server detect a repeat and return the original result instead of acting twice. It's the cheapest defense against duplicate actions, the most damaging failure mode under load.

Bringing agentic AI to your phone lines

Reliable tool-wiring is exactly what makes a voice agent trustworthy. CallSphere applies these MCP patterns to voice and chat — assistants that answer every call, take real actions mid-conversation, and book work 24/7 without double-acting. See it 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.