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.

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
Large results	Use `_meta["anthropic/maxResultSizeChars"]` annotation (up to 500K) for results that lose meaning when truncated (CC 2.1.91)

Spec & Governance

Protocol: Model Context Protocol, spec version 2025-11-25 (latest stable)
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
2026 model: Working Groups and Interest Groups are now the primary vehicle for protocol evolution (no more milestone-based releases). Enterprise readiness lands as extensions, not core spec changes.

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

SDK landscape (2026-Q2)

Package	What it is	When to use
`mcp` (PyPI) >=1.27	Official Python SDK — includes the `FastMCP` helper, transport adapters, Inspector	New Python servers. This is the canonical package.
`@modelcontextprotocol/sdk` (npm) >=1.29	Official TypeScript SDK	New TS servers
`fastmcp` (PyPI)	Standalone fork by jlowin — predates `mcp`; API-compatible but diverges on lifespan and middleware	Existing projects pinned to it. New projects should prefer `mcp`.

The fastmcp fork and the mcp.server.fastmcp module are not the same package. Imports and pyproject.toml entries must agree or stacktraces become cryptic.

Debugging with Claude Code

Pass --mcp-debug to Claude Code when troubleshooting server wiring — it surfaces the raw JSON-RPC frames, handshake failures, and tool-registration events that the default logger swallows:

claude --mcp-debug "query the local test server"
# or per-session:
export CLAUDE_MCP_DEBUG=1

Use alongside the MCP Inspector (npx @modelcontextprotocol/inspector <cmd>) — Inspector gives you the client-side frame view, --mcp-debug gives you what Claude actually saw.

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 without _meta annotation — use _meta["anthropic/maxResultSizeChars"] to declare intentionally large results (DB schemas, API specs) so clients/hooks don't truncate them
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

mcp-patterns