mcp-patterns

MCP 模式

构建、组合和保护 Model Context Protocol 服务的模式。基于 2025-11-25 规范——由 Agentic AI Foundation（Linux Foundation）维护的最新稳定版本，该基金会由 Anthropic、Block 和 OpenAI 共同创立。

要搭建新服务？ 使用 Anthropic 的 mcp-builder 技能（来自 anthropics/skills marketplace：/plugin marketplace add anthropics/skills）进行项目设置并创建评估。本技能聚焦于初始设置之后的模式、安全和高级功能。

要部署到 Cloudflare？ 请参阅 building-mcp-server-on-cloudflare 技能，了解 Workers 专用的部署模式。

迁移之前，请固定使用 mcp<2。 本技能中的所有 Python 代码片段都面向 v1 SDK （from mcp.server.fastmcp import FastMCP）。Python SDK 已发布 2.0.0，pip install mcp 现在会解析到该版本，而上游自己的 README 也建议在迁移之前，将依赖版本上限设为 <2。 FastMCP 在 2.0 README 中完全没有出现，因此应将这些代码片段视为仅适用于 v1，不要假设它们仍然适用。v1.x 仍会在自己的分支上获得关键错误和安全修复。已于 2026-07-31 验证。 迁移指南：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

快速参考

类别	规则	影响	关键模式
服务端	server-setup.md	高	FastMCP 生命周期、Tool/Resource/Prompt 原语
服务端	server-transport.md	高	CLI 使用 stdio，生产环境使用 Streamable HTTP
身份验证	auth-oauth21.md	高	PKCE、RFC 8707 资源指示符、令牌验证
高级	advanced-composition.md	中	管道、并行和分支工具组合
高级	advanced-resources.md	中	资源缓存、TTL、LRU 淘汰和生命周期
高级	elicitation.md	中	服务端向用户发起结构化输入请求
高级	sampling-tools.md	中	服务端工具调用 Agent 循环
高级	apps-ui.md	中	通过 MCP Apps + @mcp-ui/* SDK 实现交互式 UI
客户端	client-patterns.md	中	TypeScript/Python MCP 客户端连接模式
安全	security-injection.md	高	描述清理、编码规范化
安全	security-hardening.md	高	零信任允许列表、哈希验证、rug pull 检测
质量	testing-debugging.md	中	MCP Inspector、单元测试、传输调试
生态系统	registry-discovery.md	低	官方注册表 API、服务元数据
生态系统	webmcp-browser.md	低	W3C 浏览器原生 Agent 工具（互补）

共计：6 个类别中的 14 条规则

关键决策

决策	建议
传输方式	CLI/桌面应用使用 stdio，生产环境使用 Streamable HTTP（SSE 已弃用）
语言	生产环境使用 TypeScript（SDK 支持更好，类型安全）
身份验证	使用带 PKCE（S256）的 OAuth 2.1 + RFC 8707 资源指示符
服务生命周期	始终使用 FastMCP 生命周期管理资源
错误处理	将错误作为文本内容返回（Claude 可以理解并重试）
工具组合	顺序执行使用管道，并行执行使用 asyncio.gather
资源缓存	使用 TTL + LRU 淘汰，并设置内存上限
工具信任模型	零信任：显式允许列表 + 哈希验证
用户输入	运行时输入使用 Elicitation；绝不通过 elicitation 请求个人身份信息
交互式 UI	使用 MCP Apps 和 @mcp-ui/* SDK；对所有 iframe 进行沙箱隔离
令牌处理	绝不将客户端令牌透传给下游服务
大型结果	对截断后会失去意义的结果，使用 _meta["anthropic/maxResultSizeChars"] 注解（最高 500K）（CC 2.1.91）

规范与治理

• 协议：Model Context Protocol，规范版本 2025-11-25（最新稳定版）
• 治理：Agentic AI Foundation（Linux Foundation，2025 年 12 月）
• 白金会员：AWS、Anthropic、Block、Bloomberg、Cloudflare、Google、Microsoft、OpenAI
• 采用情况：超过 10,000 个服务；Claude、Cursor、Copilot、Gemini、ChatGPT、VS Code
• 规范 URL：https://modelcontextprotocol.io/specification/2025-11-25
• 2026 年模式：工作组和兴趣组现已成为推动协议演进的主要方式（不再按里程碑发布）。企业就绪能力通过扩展实现，而非修改核心规范。

功能成熟度

功能	规范版本	状态
工具、资源、提示词	2024-11-05	稳定
Streamable HTTP 传输	2025-03-26	稳定（取代 SSE）
OAuth 2.1 + Elicitation（表单）	2025-06-18	稳定
带工具调用的 Sampling	2025-11-25	稳定
Elicitation URL 模式	2025-11-25	稳定
MCP Apps（UI 扩展）	2026-01-26	扩展（ext-apps）
WebMCP（浏览器原生）	2026-02-14	W3C 社区草案

SDK 概况（2026-Q2）

软件包	说明	适用场景
mcp（PyPI）>=1.27	官方 Python SDK — 包含 FastMCP 辅助工具、传输适配器和 Inspector	新建 Python 服务。这是规范的软件包。
@modelcontextprotocol/sdk（npm）>=1.29	官方 TypeScript SDK	新建 TS 服务
fastmcp（PyPI）	jlowin 独立维护的分支 — 早于 mcp；API 兼容，但在生命周期和中间件方面有所不同	已固定使用该软件包的现有项目。新项目应优先选择 mcp。

fastmcp 分支和 mcp.server.fastmcp 模块不是同一个软件包。导入语句和 pyproject.toml 条目必须保持一致，否则堆栈跟踪会变得晦涩难懂。

使用 Claude Code 调试

排查服务连接问题时，向 Claude Code 传入 --mcp-debug——它会显示原始 JSON-RPC 帧、握手失败和工具注册事件，这些信息会被默认日志记录器吞掉：

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

与 MCP Inspector（npx @modelcontextprotocol/inspector <cmd>）搭配使用——Inspector 提供客户端帧视图，--mcp-debug 则显示 Claude 实际看到的内容。

CC 2.1.128 — 重连时的工具摘要：会话中途服务重新连接时，重新发布的工具会汇总显示为 mcp__<server>__* (N tools re-registered)，而不是逐行列出。以初始连接事件作为工具清单的准确信息来源；重连摘要仅视为增量。参见 references/mcp-audit-runbook.md，其中包含适用于这两种格式的 grep 用法。

CC 2.1.133 — MCP OAuth 支持 HTTP(S)_PROXY / NO_PROXY / mTLS：完整的 MCP OAuth 流程（发现、动态客户端注册、令牌交换、令牌刷新）现在端到端支持标准代理和客户端证书环境变量。位于企业代理之后的企业部署不再需要 OAuth 专用变通方案——现有用于路由 MCP 传输的 HTTPS_PROXY / NO_PROXY / NODE_EXTRA_CA_CERTS 配置现在也会路由身份验证。环境变量示例请参见 configure/references/cc-version-settings.md（CC 2.1.133 部分）。配套部署技能 building-mcp-server-on-cloudflare 可以删除此前有关“代理感知的 OAuth 需要手动处理”的注意事项。

**CC 2.1.169 — 托管 MCP 策略全面生效：**企业的 allowedMcpServers/deniedMcpServers 现在适用于重新连接、IDE 类型的配置、安装后首个会话中的 --mcp-config 服务，以及远程设置加载之前（此前这四种情况都跳过了策略执行）。没有远程设置的组织也能更快地冷启动。如果此前正常工作的服务在 2.1.169 后停止连接，请先检查托管策略，再调试服务。

**CC 2.1.163 — stdio 服务获得 CLAUDE_CODE_SESSION_ID：**使用 --resume 时，stdio MCP 服务现在也会收到 CLAUDE_CODE_SESSION_ID 环境变量，hooks 和 Bash 原本就会收到该变量。在服务中读取此变量，可关联恢复会话之间的日志/遥测信息，而无需自行生成会话密钥——但切勿使用它作为身份验证令牌的键（参见常见错误 #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])

常见错误

1. 缺少生命周期管理（关闭时导致连接/资源泄漏）
2. 未对工具参数进行输入验证
3. 在工具输出中返回机密（API 密钥、凭据）
   • CC 2.1.161 在 CLI 层面缓解了这一问题：claude mcp list/get/add 不再展开 ${VAR} 引用，并会在终端输出中隐藏凭据标头和 URL 机密信息——但服务代码仍绝不能在工具结果中返回机密。/mcp 还会将从未登录过的连接器折叠到“显示未使用的连接器”行下。
   • CC 2.1.186 为基于 OAuth 的服务（HTTP/SSE/连接器）新增了 claude mcp login <name> / claude mcp logout <name>。传入 --no-browser 可打印授权 URL，而不打开浏览器——这是 SSH/无头/远程会话的受支持方式（出现提示时，将重定向 URL 粘贴回来），因此仅支持交互式的身份验证不会阻塞自动化设置。
4. 响应大小不受限制且没有 _meta 注解——使用 _meta["anthropic/maxResultSizeChars"] 声明有意设置的大型结果（数据库架构、API 规范），以避免客户端/hooks 将其截断
5. 未经净化就信任工具描述（存在注入风险）
6. 未对工具调用进行哈希验证（存在恶意替换漏洞）
7. 在会话 ID 中存储身份验证令牌（凭据泄漏）
8. 在异步服务中运行阻塞式同步代码（使用 asyncio.to_thread()）
9. 使用 SSE 传输而非 Streamable HTTP（自 2025 年 3 月起已弃用）
10. 将客户端令牌传递给下游服务（混淆代理问题）

生态系统

资源	用途
mcp-builder skill (anthropics/skills)	搭建新的 MCP 服务并创建评估
building-mcp-server-on-cloudflare skill	在 Cloudflare Workers 上部署 MCP 服务
@mcp-ui/* packages (npm)	实现 MCP Apps UI 标准
MCP Registry	发现服务：https://registry.modelcontextprotocol.io/
MCP Inspector	交互式调试和测试服务

相关技能

• ork:llm-integration — LLM 函数调用模式
• ork:security-patterns — 通用输入净化和分层安全
• ork:api-design — REST/GraphQL API 设计模式