/mcp-patterns

name: mcp-patterns
license: MIT
compatibility: "Claude Code 2.1.277+."
description: MCP server building, advanced patterns, and security hardening. Use when building MCP servers, implementing tool handlers, choosing a transport, adding OAuth, wiring MCP Apps UI with @mcp-ui, hardening MCP security, or debugging MCP integrations.
user-invocable: false
effort: high
targets:
  - library: "@modelcontextprotocol/sdk"
    version: ">=1.31.0"
  # Upper bound is deliberate, not a lag. `pip install mcp` now resolves to 2.x,
  # and the 2.0 README says to keep a `<2` bound until you have migrated. Every
  # Python snippet in this skill is v1 (`from mcp.server.fastmcp import FastMCP`),
  # and FastMCP is not mentioned anywhere in the 2.0 README. Verified 2026-07-31.
  # Remove the ceiling only together with a migration of rules/*.md.
  - library: "mcp"
    version: ">=1.28.0,<2.0.0"
metadata:
  category: mcp-enhancement
  spec-version: "2025-11-25"
  version: "3.1.0"
  author: "OrchestKit"
  complexity: "high"
  tags: "mcp, server, tools, resources, security, prompt-injection, oauth, elicitation, sampling, mcp-apps, fastmcp"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
paths:
  - ".mcp.json"
  - "**/*.mcp.json"

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](https://agenticaifoundation.org/) (Linux Foundation), co-founded by Anthropic, Block, and OpenAI.

> **Scaffolding a new server?** Use Anthropic's `mcp-builder` skill (from the `anthropics/skills` marketplace: `/plugin marketplace add 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.

> **Pin `mcp<2` until you migrate.** Every Python snippet in this skill targets the v1 SDK > (`from mcp.server.fastmcp import FastMCP`). The Python SDK released **2.0.0**, `pip install mcp` > now resolves to it, and upstream's own README says to keep a `<2` upper bound on your requirement > until you have migrated. `FastMCP` does not appear anywhere in the 2.0 README, so treat these > snippets as v1-only rather than assuming they still apply. v1.x continues to receive critical bug > and security fixes on its own branch. Verified 2026-07-31. > Migration guide: https://py.sdk.modelcontextprotocol.io/migration/

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 ru