菜单
MCP server building, advanced patterns, and security hardening. Use when building MCP servers, implementing tool handlers, choosing a transport, adding OAuth authentication, wiring MCP Apps UI with @mcp-ui, hardening MCP security, or debugging MCP integrations.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/yonatangross/orchestkit --skill mcp-patterns命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | mcp-patterns |
| license | MIT |
| compatibility | Claude Code 2.1.220+. |
| author | OrchestKit |
| description | MCP server building, advanced patterns, and security hardening. Use when building MCP servers, implementing tool handlers, choosing a transport, adding OAuth authentication, wiring MCP Apps UI with @mcp-ui, hardening MCP security, or debugging MCP integrations. |
| version | 3.1.0 |
| tags | ["mcp","server","tools","resources","security","prompt-injection","oauth","elicitation","sampling","mcp-apps","fastmcp"] |
| user-invocable | false |
| disable-model-invocation | true |
| context | fork |
| complexity | high |
| persuasion-type | reference |
| effort | high |
| targets | [{"library":"@modelcontextprotocol/sdk","version":">=1.29.0"},{"library":"mcp","version":">=1.28.0,<2.0.0"}] |
| metadata | {"category":"mcp-enhancement","spec-version":"2025-11-25"} |
| allowed-tools | ["Read","Glob","Grep","WebFetch","WebSearch"] |
| paths | [".mcp.json","**/*.mcp.json"] |
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-builderskill (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-cloudflareskill for Workers-specific deployment patterns.
Pin
mcp<2until 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 mcpnow resolves to it, and upstream's own README says to keep a<2upper bound on your requirement until you have migrated.FastMCPdoes 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/
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
| 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
| 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) |
| 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 |
| 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
fastmcpfork and themcp.server.fastmcpmodule are not the same package. Imports andpyproject.tomlentries must agree or stacktraces become cryptic.
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.
CC 2.1.128 — reconnect tool summarization: when a server reconnects mid-session, re-announced tools are summarized as
mcp__<server>__* (N tools re-registered)instead of being enumerated line-by-line. Use the initial connect event as the source of truth for tool inventory; treat reconnect summaries as deltas only. Seereferences/mcp-audit-runbook.mdfor grep recipes that work across both formats.
CC 2.1.133 — MCP OAuth honors HTTP(S)_PROXY / NO_PROXY / mTLS: the full MCP OAuth flow (discovery, dynamic client registration, token exchange, token refresh) now respects standard proxy and client-certificate env vars end-to-end. Enterprise deployments behind corporate proxies no longer need OAuth-specific workarounds — the same
HTTPS_PROXY/NO_PROXY/NODE_EXTRA_CA_CERTSconfig that already routes MCP transport now also routes auth. Seeconfigure/references/cc-version-settings.md(CC 2.1.133 section) for the env-var example. The companion deployment skillbuilding-mcp-server-on-cloudflarecan drop any prior "proxy-aware OAuth requires manual handling" caveat at this floor.
CC 2.1.169 — managed MCP policies enforced everywhere: enterprise
allowedMcpServers/deniedMcpServersnow apply on reconnect, IDE-typed configs,--mcp-configservers in the first session after install, and before remote settings load (previously all four paths skipped enforcement). Orgs without remote settings also get faster cold starts. If a previously-working server stops connecting after 2.1.169, check the managed policy before debugging the server.
CC 2.1.163 — stdio servers get
CLAUDE_CODE_SESSION_ID: on--resume, stdio MCP servers now receive the sameCLAUDE_CODE_SESSION_IDenv var that hooks and Bash already get. Read it inside the server to correlate logs/telemetry across resumed sessions instead of minting your own session key — but never store auth tokens keyed off it (see Common Mistake #7).
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])
claude mcp list/get/add no longer expands ${VAR} references and redacts credential headers and URL secrets in terminal output — but server code must still never return secrets in tool results. /mcp also collapses never-signed-in connectors behind a "Show unused connectors" row.claude mcp login <name> / claude mcp logout <name> for OAuth-backed servers (HTTP/SSE/connector). Pass --no-browser to print the authorization URL instead of opening a browser — the supported path for SSH/headless/remote sessions (paste the redirect URL back when prompted), so interactive-only auth never blocks automated setup._meta annotation — use _meta["anthropic/maxResultSizeChars"] to declare intentionally large results (DB schemas, API specs) so clients/hooks don't truncate themasyncio.to_thread())| 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 |
ork:llm-integration — LLM function calling patternsork:security-patterns — General input sanitization and layered securityork:api-design — REST/GraphQL API design patterns