MCP Patterns
Patterns for building, composing, and securing Model Context Protocol servers. Based on the 2025-11-25 specification — the latest stable release maintained by the Agentic AI Foundation (Linux Foundation), co-founded by Anthropic, Block, and OpenAI.
Scaffolding a new server? Use Anthropic's mcp-builder skill (claude install anthropics/skills) for project setup and evaluation creation. This skill focuses on patterns, security, and advanced features after initial setup.
Deploying to Cloudflare? See the building-mcp-server-on-cloudflare skill for Workers-specific deployment patterns.
Decision Tree — Which Rule to Read
What are you building?
│
├── New MCP server
│ ├── Setup & primitives ──────► rules/server-setup.md
│ ├── Transport selection ─────► rules/server-transport.md
│ └── Scaffolding ─────────────► mcp-builder skill (anthropics/skills)
│
├── Authentication & authorization
│ └── OAuth 2.1 + OIDC ───────► rules/auth-oauth21.md
│
├── Advanced server features
│ ├── Tool composition ────────► rules/advanced-composition.md
│ ├── Resource caching ────────► rules/advanced-resources.md
│ ├── Elicitation (user input) ► rules/elicitation.md
│ ├── Sampling (agent loops) ──► rules/sampling-tools.md
│ └── Interactive UI ──────────► rules/apps-ui.md
│
├── Client-side consumption
│ └── Connecting to servers ───► rules/client-patterns.md
│
├── Security hardening
│ ├── Prompt injection defense ► rules/security-injection.md
│ └── Zero-trust & verification ► rules/security-hardening.md
│
├── Testing & debugging
│ └── Inspector + unit tests ──► rules/testing-debugging.md
│
├── Discovery & ecosystem
│ └── Registries & catalogs ──► rules/registry-discovery.md
│
└── Browser-native tools
└── WebMCP (W3C) ───────────► rules/webmcp-browser.md
Quick Reference
| Category |
Rule |
Impact |
Key Pattern |
| Server |
server-setup.md |
HIGH |
FastMCP lifespan, Tool/Resource/Prompt primitives |
| Server |
server-transport.md |
HIGH |
stdio for CLI, Streamable HTTP for production |
| Auth |
auth-oauth21.md |
HIGH |
PKCE, RFC 8707 resource indicators, token validation |
| Advanced |
advanced-composition.md |
MEDIUM |
Pipeline, parallel, and branching tool composition |
| Advanced |
advanced-resources.md |
MEDIUM |
Resource caching with TTL, LRU eviction, lifecycle |
| Advanced |
elicitation.md |
MEDIUM |
Server-initiated structured input from users |
| Advanced |
sampling-tools.md |
MEDIUM |
Server-side agent loops with tool calling |
| Advanced |
apps-ui.md |
MEDIUM |
Interactive UI via MCP Apps + @mcp-ui/* SDK |
| Client |
client-patterns.md |
MEDIUM |
TypeScript/Python MCP client connection patterns |
| Security |
security-injection.md |
HIGH |
Description sanitization, encoding normalization |
| Security |
security-hardening.md |
HIGH |
Zero-trust allowlist, hash verification, rug pull detection |
| Quality |
testing-debugging.md |
MEDIUM |
MCP Inspector, unit tests, transport debugging |
| Ecosystem |
registry-discovery.md |
LOW |
Official registry API, server metadata |
| Ecosystem |
webmcp-browser.md |
LOW |
W3C browser-native agent tools (complementary) |
Total: 14 rules across 6 categories
Key Decisions
| Decision |
Recommendation |
| Transport |
stdio for CLI/Desktop, Streamable HTTP for production (SSE deprecated) |
| Language |
TypeScript for production (better SDK support, type safety) |
| Auth |
OAuth 2.1 with PKCE (S256) + RFC 8707 resource indicators |
| Server lifecycle |
Always use FastMCP lifespan for resource management |
| Error handling |
Return errors as text content (Claude can interpret and retry) |
| Tool composition |
Pipeline for sequential, asyncio.gather for parallel |
| Resource caching |
TTL + LRU eviction with memory cap |
| Tool trust model |
Zero-trust: explicit allowlist + hash verification |
| User input |
Elicitation for runtime input; never request PII via elicitation |
| Interactive UI |
MCP Apps with @mcp-ui/* SDK; sandbox all iframes |
| Token handling |
Never pass through client tokens to downstream services |
Spec & Governance
- Protocol: Model Context Protocol, spec version 2025-11-25
- Governance: Agentic AI Foundation (Linux Foundation, Dec 2025)
- Platinum members: AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI
- Adoption: 10,000+ servers; Claude, Cursor, Copilot, Gemini, ChatGPT, VS Code
- Spec URL: https://modelcontextprotocol.io/specification/2025-11-25
Feature Maturity
| Feature |
Spec Version |
Status |
| Tools, Resources, Prompts |
2024-11-05 |
Stable |
| Streamable HTTP transport |
2025-03-26 |
Stable (replaces SSE) |
| OAuth 2.1 + Elicitation (form) |
2025-06-18 |
Stable |
| Sampling with tool calling |
2025-11-25 |
Stable |
| Elicitation URL mode |
2025-11-25 |
Stable |
| MCP Apps (UI extension) |
2026-01-26 |
Extension (ext-apps) |
| WebMCP (browser-native) |
2026-02-14 |
W3C Community Draft |
Example
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-server")
@mcp.tool()
async def search(query: str) -> str:
"""Search documents. Returns matching results."""
results = await db.search(query)
return "\n".join(r.title for r in results[:10])
Common Mistakes
- No lifecycle management (connection/resource leaks on shutdown)
- Missing input validation on tool arguments
- Returning secrets in tool output (API keys, credentials)
- Unbounded response sizes (Claude has context limits)
- Trusting tool descriptions without sanitization (injection risk)
- No hash verification on tool invocations (rug pull vulnerability)
- Storing auth tokens in session IDs (credential leak)
- Blocking synchronous code in async server (use
asyncio.to_thread())
- Using SSE transport instead of Streamable HTTP (deprecated since March 2025)
- Passing through client tokens to downstream services (confused deputy)
Ecosystem
| Resource |
What For |
mcp-builder skill (anthropics/skills) |
Scaffold new MCP servers + create evals |
building-mcp-server-on-cloudflare skill |
Deploy MCP servers on Cloudflare Workers |
@mcp-ui/* packages (npm) |
Implement MCP Apps UI standard |
| MCP Registry |
Discover servers: https://registry.modelcontextprotocol.io/ |
| MCP Inspector |
Debug and test servers interactively |
Related Skills
ork:llm-integration — LLM function calling patterns
ork:security-patterns — General input sanitization and layered security
ork:api-design — REST/GraphQL API design patterns
1---2name: mcp-patterns-23license: MIT4compatibility: "Claude Code 2.1.56+."5author: OrchestKit6description: MCP server building, advanced patterns, and security hardening. Use when building MCP servers, implementing tool handlers, adding authentication, creating interactive UIs, hardening MCP security, or debugging MCP integrations.7version: 3.0.08tags: [mcp, server, tools, resources, security, prompt-injection, oauth, elicitation, sampling, mcp-apps]9user-invocable: false10context: fork11complexity: high12metadata:13 source: https://skillmd.com/skills/diegosouzapw/mcp-patterns-214 category: mcp-enhancement15 spec-version: "2025-11-25"16---1718# MCP Patterns1920Patterns for building, composing, and securing Model Context Protocol servers. Based on the **2025-11-25 specification** — the latest stable release maintained by the [Agentic AI Foundation](https://agenticaifoundation.org/) (Linux Foundation), co-founded by Anthropic, Block, and OpenAI.2122> **Scaffolding a new server?** Use Anthropic's `mcp-builder` skill (`claude install anthropics/skills`) for project setup and evaluation creation. This skill focuses on **patterns, security, and advanced features** after initial setup.23>24> **Deploying to Cloudflare?** See the `building-mcp-server-on-cloudflare` skill for Workers-specific deployment patterns.2526## Decision Tree — Which Rule to Read2728```29What are you building?30│31├── New MCP server32│ ├── Setup & primitives ──────► rules/server-setup.md33│ ├── Transport selection ─────► rules/server-transport.md34│ └── Scaffolding ─────────────► mcp-builder skill (anthropics/skills)35│36├── Authentication & authorization37│ └── OAuth 2.1 + OIDC ───────► rules/auth-oauth21.md38│39├── Advanced server features40│ ├── Tool composition ────────► rules/advanced-composition.md41│ ├── Resource caching ────────► rules/advanced-resources.md42│ ├── Elicitation (user input) ► rules/elicitation.md43│ ├── Sampling (agent loops) ──► rules/sampling-tools.md44│ └── Interactive UI ──────────► rules/apps-ui.md45│46├── Client-side consumption47│ └── Connecting to servers ───► rules/client-patterns.md48│49├── Security hardening50│ ├── Prompt injection defense ► rules/security-injection.md51│ └── Zero-trust & verification ► rules/security-hardening.md52│53├── Testing & debugging54│ └── Inspector + unit tests ──► rules/testing-debugging.md55│56├── Discovery & ecosystem57│ └── Registries & catalogs ──► rules/registry-discovery.md58│59└── Browser-native tools60 └── WebMCP (W3C) ───────────► rules/webmcp-browser.md61```6263## Quick Reference6465| Category | Rule | Impact | Key Pattern |66|----------|------|--------|-------------|67| **Server** | `server-setup.md` | HIGH | FastMCP lifespan, Tool/Resource/Prompt primitives |68| **Server** | `server-transport.md` | HIGH | stdio for CLI, Streamable HTTP for production |69| **Auth** | `auth-oauth21.md` | HIGH | PKCE, RFC 8707 resource indicators, token validation |70| **Advanced** | `advanced-composition.md` | MEDIUM | Pipeline, parallel, and branching tool composition |71| **Advanced** | `advanced-resources.md` | MEDIUM | Resource caching with TTL, LRU eviction, lifecycle |72| **Advanced** | `elicitation.md` | MEDIUM | Server-initiated structured input from users |73| **Advanced** | `sampling-tools.md` | MEDIUM | Server-side agent loops with tool calling |74| **Advanced** | `apps-ui.md` | MEDIUM | Interactive UI via MCP Apps + @mcp-ui/* SDK |75| **Client** | `client-patterns.md` | MEDIUM | TypeScript/Python MCP client connection patterns |76| **Security** | `security-injection.md` | HIGH | Description sanitization, encoding normalization |77| **Security** | `security-hardening.md` | HIGH | Zero-trust allowlist, hash verification, rug pull detection |78| **Quality** | `testing-debugging.md` | MEDIUM | MCP Inspector, unit tests, transport debugging |79| **Ecosystem** | `registry-discovery.md` | LOW | Official registry API, server metadata |80| **Ecosystem** | `webmcp-browser.md` | LOW | W3C browser-native agent tools (complementary) |8182**Total: 14 rules across 6 categories**8384## Key Decisions8586| Decision | Recommendation |87|----------|----------------|88| Transport | stdio for CLI/Desktop, Streamable HTTP for production (SSE deprecated) |89| Language | TypeScript for production (better SDK support, type safety) |90| Auth | OAuth 2.1 with PKCE (S256) + RFC 8707 resource indicators |91| Server lifecycle | Always use FastMCP lifespan for resource management |92| Error handling | Return errors as text content (Claude can interpret and retry) |93| Tool composition | Pipeline for sequential, `asyncio.gather` for parallel |94| Resource caching | TTL + LRU eviction with memory cap |95| Tool trust model | Zero-trust: explicit allowlist + hash verification |96| User input | Elicitation for runtime input; never request PII via elicitation |97| Interactive UI | MCP Apps with @mcp-ui/* SDK; sandbox all iframes |98| Token handling | Never pass through client tokens to downstream services |99100## Spec & Governance101102- **Protocol**: Model Context Protocol, spec version **2025-11-25**103- **Governance**: Agentic AI Foundation (Linux Foundation, Dec 2025)104- **Platinum members**: AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft, OpenAI105- **Adoption**: 10,000+ servers; Claude, Cursor, Copilot, Gemini, ChatGPT, VS Code106- **Spec URL**: https://modelcontextprotocol.io/specification/2025-11-25107108### Feature Maturity109110| Feature | Spec Version | Status |111|---------|-------------|--------|112| Tools, Resources, Prompts | 2024-11-05 | Stable |113| Streamable HTTP transport | 2025-03-26 | Stable (replaces SSE) |114| OAuth 2.1 + Elicitation (form) | 2025-06-18 | Stable |115| Sampling with tool calling | 2025-11-25 | Stable |116| Elicitation URL mode | 2025-11-25 | Stable |117| MCP Apps (UI extension) | 2026-01-26 | Extension (ext-apps) |118| WebMCP (browser-native) | 2026-02-14 | W3C Community Draft |119120## Example121122```python123from mcp.server.fastmcp import FastMCP124125mcp = FastMCP("my-server")126127@mcp.tool()128async def search(query: str) -> str:129 """Search documents. Returns matching results."""130 results = await db.search(query)131 return "\n".join(r.title for r in results[:10])132```133134## Common Mistakes1351361. No lifecycle management (connection/resource leaks on shutdown)1372. Missing input validation on tool arguments1383. Returning secrets in tool output (API keys, credentials)1394. Unbounded response sizes (Claude has context limits)1405. Trusting tool descriptions without sanitization (injection risk)1416. No hash verification on tool invocations (rug pull vulnerability)1427. Storing auth tokens in session IDs (credential leak)1438. Blocking synchronous code in async server (use `asyncio.to_thread()`)1449. Using SSE transport instead of Streamable HTTP (deprecated since March 2025)14510. Passing through client tokens to downstream services (confused deputy)146147## Ecosystem148149| Resource | What For |150|----------|----------|151| `mcp-builder` skill (anthropics/skills) | Scaffold new MCP servers + create evals |152| `building-mcp-server-on-cloudflare` skill | Deploy MCP servers on Cloudflare Workers |153| `@mcp-ui/*` packages (npm) | Implement MCP Apps UI standard |154| MCP Registry | Discover servers: https://registry.modelcontextprotocol.io/ |155| MCP Inspector | Debug and test servers interactively |156157## Related Skills158159- `ork:llm-integration` — LLM function calling patterns160- `ork:security-patterns` — General input sanitization and layered security161- `ork:api-design` — REST/GraphQL API design patterns