12 Reusable MCP Design Patterns for Production‑Grade Anthropic Agents

Why Production‑Grade Agents Need More Than Simple API Wrappers

After the Claude Code source leak, twelve “Agentic Harness” patterns were extracted and later combined with fourteen Anthropic Skill patterns. The remaining challenge is connecting agents to real business tools, permission systems, and data sources safely, reliably, and cost‑effectively.

Anthropic’s article Building agents that reach production systems with MCP compares direct API calls, CLI, and MCP, concluding that production agents increasingly rely on MCP.

Tool Surface (How Agents See and Call Tools)

1. Remote‑First Server Pattern – Determines where the MCP server runs. Local stdio servers are convenient for desktop or IDE agents but become unstable in production where agents may run in browsers, mobile, or cloud environments. A remote‑first design lets a single server serve many clients, reuse authentication, and be independently deployed, monitored, and audited. The cost is handling latency, availability, rate‑limits, security boundaries, logging, and operations.

2. Intent‑Grouped Tools Pattern – Groups low‑level API calls behind a higher‑level intent (e.g., create_issue_from_thread) instead of exposing each endpoint ( get_thread, parse_messages, create_issue, link_attachment). This reduces the model’s orchestration burden, centralises error handling, and aligns tools with user tasks. The trade‑off is the need to design each grouped tool’s name, parameters, return schema, and error handling.

3. Thin Surface Pattern – For massive APIs (AWS, Cloudflare, Kubernetes) exposing every endpoint would explode the context window. The thin surface approach offers only a few high‑capability tools (e.g., search, execute) while hiding thousands of endpoints behind them. Cloudflare’s MCP server demonstrates this: two tools cover ~2,500 endpoints using ~1,000 tokens. The downside is the requirement for a secure sandbox, resource limits, timeout policies, and audit mechanisms.

4. Inline UI Pattern – Some results (charts, tables, dashboards, file previews, approval forms) are better shown directly to the user rather than converted to text. MCP Apps allow a tool to return an interactive UI that the client renders inline, turning the server into a partial UI provider. This is ideal when visual fidelity outweighs textual description, but it forces the server team to consider component versions, accessibility, visual consistency, and client compatibility.

5. Elicited Input (Form Mode) Pattern – When a tool call lacks required structured parameters (e.g., region, environment, project ID), the server can pause the workflow, return a form schema, and let the client render a form for the user to fill. This avoids risky guessing or disruptive follow‑up questions. The cost is additional UX design; poorly designed forms feel like interrogation, and the pattern is unsuitable for headless or batch agents.

6. External Handoff Pattern – Sensitive operations (OAuth flows, payments, secret handling) should not pass through the MCP client. Instead, the server returns a URL that the client opens in an external browser or app, letting the user complete the flow before resuming the agent. This isolates high‑risk data but introduces potential user drop‑off and requires a resume‑after‑redirect mechanism.

Interaction Semantics (What Tools Return)

Early agents returned plain text or JSON, which works for simple queries but loses structure for logs, metrics, or rich UI elements. MCP is evolving to let tools return UI fragments, request additional structured input, or hand off to external flows, preserving fidelity and reducing token waste.

7. Inline UI Pattern – Allows tools to return interactive UI (charts, tables, dashboards, search results, file previews, approval forms) that the client renders directly, avoiding the loss of detail that occurs when large JSON payloads are summarised into text.

8. Elicited Input Pattern – MCP’s Form Mode elicitation lets a server, during a tool call, return a form schema. The client renders the form, the user fills it, and control returns to the server. This is useful when required parameters are missing (e.g., region, environment) or when multiple candidate options need user selection. The trade‑off is the need for UX design and the pattern’s incompatibility with headless workflows.

9. External Handoff Pattern – For highly sensitive flows (third‑party OAuth, payments, credential entry), the server returns a URL. The client opens the URL, the user completes the flow, and the agent resumes. This isolates secrets but adds a potential drop‑off point and requires resume‑after‑redirect handling.

Auth and Credential Flow (Secure Access)

10. Discoverable Auth Pattern – Instead of each server defining a custom auth scheme, MCP supports standard OAuth metadata (Client ID Metadata Documents). Clients can discover authentication requirements automatically, reducing configuration friction and failure rates.

11. Vault‑Held Credentials Pattern – Credentials are stored in a platform vault rather than passed in tool parameters or environment variables. Anthropic’s MCP OAuth credential registers a vault ID; the platform injects the appropriate token at runtime, handling refresh, revocation, and lifecycle management. This centralises secret handling but requires trust in the vault’s security, availability, and audit capabilities.

Context Economy (Managing Token Budgets)

12. On‑Demand Tool Loading Pattern – When an agent connects to many MCP servers, loading all tool definitions would consume a large portion of the context window. A tool‑search utility lets the agent discover only the needed tools, reducing definition tokens by >85% while maintaining selection accuracy.

13. Programmatic Tool Calling Pattern – Instead of feeding raw tool results (large logs, JSON blobs) to the model, the agent runs a short script in a sandbox to filter, aggregate, and summarise data before returning the concise result. Anthropic’s tests show a ~37% token reduction for complex multi‑step workflows. The trade‑off is the need for a code sandbox and debugging support.

Packaging and Distribution (Deploying Complete Capabilities)

14. Plugin Bundle Pattern – Packages MCP servers, Skills, hooks, sub‑agents, and optional LSP servers into a single plugin (e.g., Claude Code plugins). Users install one bundle and receive a complete capability set. The benefit is reduced installation friction; the cost is tighter version coupling—any component change may require a new plugin version.

15. Server‑Distributed Skills Pattern – Beyond exposing tools, a server can also distribute the Skills (playbooks) that teach the agent how to use those tools safely and effectively. This turns the server into a source of both capabilities and usage guidance, shifting the competitive edge from “who has more tools” to “who delivers tools, processes, experience, and security together.”

Conclusion

The twelve patterns break down the engineering challenges of moving an agent from demo to production: where the server runs, how tools are exposed, how users interact, how authentication is handled, how context is managed, and how capabilities are packaged. Understanding and applying these patterns is essential for building production‑grade AI agents.

References:

[1] Building agents that reach production systems with MCP – https://claude.com/blog/building-agents-that-reach-production-systems-with-mcp

[2] Cloudflare MCP Server – https://github.com/cloudflare/mcp

[3] MCP Apps – https://modelcontextprotocol.io/extensions/apps/overview

[4] Form Mode elicitation – https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation#form-mode-elicitation-requests

[5] Client ID Metadata Documents – https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents

[6] MCP OAuth credential – https://platform.claude.com/docs/en/managed-agents/vaults#mcp-oauth-credential

[7] Tool search tool – https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool

[8] Programmatic tool calling – https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling

[9] 12 MCP Patterns Behind Production Agents – https://generativeprogrammer.com/p/12-mcp-patterns-behind-production

[10] Writing tools for agents – https://www.anthropic.com/engineering/writing-tools-for-agents