MCP教程：使用2026-07-28规范从零到生产服务器

关键要点

• MCP SDK月下载量超过9700万，但仅8.5%的服务器使用OAuth — 协议的采用速度超过了其安全态势，使本教程中的生产强化步骤对任何B2B部署都不可或缺。
• MCP SDK v2将包体积缩减83%，速度提升25% — 2026-07-28规范与重新设计的TypeScript、Python、Go和C# SDK一同发布，每个都有迁移指南。
• 2026-07-28规范移除了会话和初始化握手 — 每个请求现在都是自包含的，可落在普通轮询负载均衡器后的任何服务器实例上，无需共享状态。
• 8月22日MCP路线图定义了五个优先领域 — 代理身份、HTTP传输统一、代理消息原语、改进的工具原语和SDK开发者体验 — 本教程的生产路径涵盖了每一项。
• 82%的MCP服务器存在路径遍历漏洞（据Practical DevSecOps） — 此处的沙箱化和输入验证步骤是演示与部署之间的区别。

Model Context Protocol在2026年突破了9700万月SDK下载量，TypeScript和Python SDK各自超过10亿总下载量。2026-07-28规范发布了自推出以来的最大修订：无状态协议核心、一等扩展和三个简化部署面的弃用。三周后，8月22日，MCP维护者发布了新路线图，定义了下一规范周期的五个优先领域 — 代理身份、HTTP传输统一、代理消息原语、改进的工具原语和SDK开发者体验。

本教程涵盖生产路径：构建一个无状态、水平可扩展、身份感知且为路线图企业优先级做好准备的MCP服务器。官方快速入门讲解了一个连接Claude Desktop的天气服务器。本文从该快速入门结束的地方开始 — 从可运行的演示到你会放在B2B代理系统背后的生产服务器之间的步骤。

第1步 — 使用SDK v2进行项目设置

2026-07-28规范与重新设计的SDK一同发布。TypeScript SDK v2通过新的客户端-服务器拆分，将包体积缩减约83%，性能提升25%。Python SDK 2.0+、Go SDK和C# SDK v2.0在发布日均支持2026-07-28协议版本，并有针对破坏性变更的详细迁移说明。

本教程使用Python 3.10+和uv：

uv init mcp-server
cd mcp-server
uv venv
source .venv/bin/activate
uv add "mcp[cli]"

mcp[cli]额外包带来了运行和检查服务器的CLI工具。SDK使用Python类型提示和文档字符串自动生成工具定义 — 你定义一个函数，装饰它，协议元数据就从签名中派生出来。

第2步 — 定义你的第一批工具

MCP服务器暴露三种能力类型：tools（模型调用的函数）、resources（模型读取的数据）和prompts（模板化工作流）。对于B2B服务器，tools是主要接口 — 代理如何搜索目录、生成报价或保留库存。

from mcp.server import MCPServer

mcp = MCPServer("catalog-server")

@mcp.tool()
async def search_catalog(query: str, supplier_id: str | None = None) -> str:
    """Search the supplier catalog by keyword, optionally filtered by supplier.

    Args:
        query: Search keyword (SKU, product name, or category)
        supplier_id: Optional supplier filter (e.g., "s-12")
    """
    results = await catalog.search(query=query, supplier_id=supplier_id)
    return format_results(results)

@mcp.tool()
async def get_pricing(sku: str, quantity: int) -> str:
    """Get tiered pricing for a SKU at a given quantity.

    Args:
        sku: Supplier product identifier
        quantity: Order quantity (determines pricing tier)
    """
    price = await pricing_engine.get(sku=sku, quantity=quantity)
    return f"SKU {sku}: ${price.unit_price:.2f} (tier: {price.tier_name})"

每个工具的文档字符串成为模型在其工具列表中看到的描述。类型提示成为输入模式。这是MCP Module Code Standard模式：每个工具都有类型化模式、清晰的文档字符串和单一职责。

**STDIO日志陷阱：**对于基于STDIO的服务器，切勿写入stdout — 它会破坏JSON-RPC消息流。使用标准logging模块，它写入stderr：

import logging
logger = logging.getLogger(__name__)
logger.info("Catalog search: query=%s", query)  # stderr, safe

第3步 — 传输：STDIO vs Streamable HTTP

2026-07-28规范使远程MCP服务器"与任何其他HTTP工作负载无异"（规范变更日志）。路线图的第二个优先领域 — HTTP原生传输统一 — 将此扩展到通过stdio说Streamable HTTP的本地服务器，统一为一种传输模型。

对于本地开发和桌面客户端，STDIO是默认选项：

if __name__ == "__main__":
    mcp.run(transport="stdio")

对于生产B2B部署 — 代理作为云工作负载运行，而非桌面应用 — Streamable HTTP是生产传输。服务器在负载均衡器后运行，接受带有Mcp-Method和Mcp-Name头的HTTP POST请求，并通过HTTP回复JSON-RPC：

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8080)

基于头的路由功能意味着你的网关、限流器或WAF可以直接在Mcp-Method和Mcp-Name头上进行路由和计量 — 路由决策无需解析JSON正文。这就是无状态协议设计的部署形态：轮询负载均衡器后的无状态服务器实例池，无共享会话层。

第4步 — 有状态工作流的显式句柄

无状态并不意味着状态消失。2026-07-28规范用显式句柄模式取代了隐藏的会话状态：工具创建一个句柄（order_id、quote_id、basket_id），模型在后续调用中将其作为普通参数传回。这在MCP 2026-07-28：无状态协议对B2B代理部署的意义中有详细讲解。

对于跨越五次工具调用的报价工作流 — 创建请求、搜索目录、生成报价、保留可用性、应用定价层级 — 句柄贯穿每次调用：

@mcp.tool()
async def create_request(buyer_id: str, line_items: list[dict]) -> str:
    """Create an RFQ request and return a request_id handle."""
    request = await rfq_engine.create(buyer_id, line_items)
    return f"request_id={request.id}"

@mcp.tool()
async def generate_quote(request_id: str, supplier_ids: list[str]) -> str:
    """Generate a quote from specified suppliers. Returns quote_id."""
    quote = await rfq_engine.quote(request_id, supplier_ids)
    return f"quote_id={quote.id}"

每次调用携带它需要的句柄。没有服务器在调用之间记住任何东西。如果负载均衡器将调用4路由到与调用3不同的实例，它仍然有效 — 句柄在请求中。如果审计团队一周后需要重建此工作流，请求参数中的句柄讲述了完整的故事。

第5步 — 代理身份：企业缺口

路线图的第三个优先领域 — 代理身份和企业级安全 — 对B2B部署最为重要。路线图明确指出：MCP授权今天"围绕在浏览器中批准访问的人构建"，但"越来越多的调用者是作为云工作负载运行的代理，拥有自己的身份，代表不在场的用户行事，或向子代理委托更窄的权限。"

路线图定义的前进路径：

1. DPoP (RFC 9449) — Demonstrating Proof of Possession将OAuth令牌绑定到客户端持有的密钥。仅凭被盗令牌无法从另一个进程重放请求。DPoP不决定代理被允许做什么；它使凭证更难在其预期持有者之外被重用。
2. Workload Identity Federation — IETF WIMSE工作组正在开发多系统环境中的工作负载身份架构。代理是工作负载，因此获得工作负载身份：以SPIFFE ID命名，用短期凭证认证，而非共享API密钥。
3. Enterprise-Managed Authorization (EMA) — EMA扩展将访问决策移至组织的身份提供商。MCP客户端将用户身份断言交换为Identity Assertion JWT Authorization Grant (ID-JAG)，然后将该授权交换为服务器特定的访问令牌。这支持集中分配和撤销。

对于本教程的生产服务器，最低基线是：

• **无共享API密钥。**每个代理获得短期、绑定受众的令牌。
• OAuth with DPoP。Practical DevSecOps MCP Security Statistics 2026报告发现仅8.5%的MCP服务器使用OAuth — 其余91.5%依赖API密钥或完全无认证。
• 每个信任边界的令牌交换。CoSAI令牌交换标准（8月18日发布）将令牌交换确立为代理工作流的基础控制。每个register_tools()入口点应接受任务范围的令牌，而非持久凭证。

参见MCP Security Hardening Checklist了解在生产前验证这些标准的12项控制，以及MCP Module Code Standard了解模块级防御态势。

第6步 — 渐进式工具发现：解决百工具问题

路线图的第四个优先领域 — 改进的原语 — 解决了一个具体的生产问题："连接到有百个工具的服务器意味着模型在用户提出任何问题之前就要为整个表面付费，而且工具选择随着列表增长而变差。"

路线图的答案是渐进式发现：服务器提供小入口点，随着对话缩窄而展示更多目录。服务器不再在连接时将100个工具模式倒入模型的上下文窗口，而是暴露少量顶层工具，并根据代理正在做什么动态扩展表面。

2026-07-28规范已提供构建块：

• server/discover RPC — 客户端可以在做任何其他事情之前了解服务器的能力，无需会话握手。
• tools/list with ttlMs and cacheScope — 列表响应携带缓存提示，因此客户端缓存工具目录并避免每次连接时重新获取。
• 每个请求的_meta — 协议版本、客户端信息和能力按请求传输，而非在协商的会话中。

对于有50+工具的服务器，渐进式发现模式如下：

@mcp.tool()
async def discover_tools(category: str) -> str:
    """Discover available tools in a category. Start here for a guided tour.

    Args:
        category: Tool category — 'catalog', 'pricing', 'inventory', 'orders'
    """
    available = tool_registry.by_category(category)
    return format_tool_list(available)

代理首先调用discover_tools("catalog")，获得5-8个聚焦工具的集合，仅在工作流需要时才扩展到其他类别。这保持上下文窗口精简和工具选择准确 — MCP Module Code Standard单一职责工具设计背后的同一原则。

第7步 — 部署：无状态、水平、在负载均衡器后

2026-07-28规范设计的部署形态：

                    ┌──────────────────┐
                    │  Load Balancer   │
                    │  (round-robin)   │
                    └────────┬─────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────┴────┐ ┌───────┴────┐ ┌───────┴────┐
     │ MCP Server  │ │ MCP Server  │ │ MCP Server  │
     │  Instance 1 │ │  Instance 2 │ │  Instance 3 │
     │ (stateless) │ │ (stateless) │ │ (stateless) │
     └─────────────┘ └─────────────┘ └─────────────┘
              │              │              │
              └──────────────┼──────────────┘
                             │
                    ┌────────┴─────────┐
                    │  Upstream Systems │
                    │  (NetSuite, etc.)  │
                    └──────────────────┘

无共享会话存储。无粘性会话负载均衡器。无会话重放基础设施。每个请求携带它所需的一切 — 协议版本、客户端信息、能力和句柄 — 在请求正文和头中，而非服务器端状态中。

对于生产强化：

• 沙箱化每个服务器实例。MCP Project Sandboxing Baseline（8月16日发布）要求生成进程的OS级沙箱化。使用Landlock (Linux)、Seatbelt (macOS)或Windows ACL来限制文件系统和网络访问。82%的路径遍历漏洞率（据Practical DevSecOps）是仅靠输入验证不够的证据。
• 限制每个工具的速率。MCP Module Code Standard要求每工具速率限制。MCP Ruby SDK DoS漏洞（8月16日披露）确认资源耗尽攻击是真实的攻击面。
• **记录到OpenTelemetry，而非MCP日志通道。**2026-07-28规范弃用了日志功能，转而支持stderr和OpenTelemetry。MCP服务器日志与现有可观测性管道（Datadog、CloudWatch、Honeycomb）集成，无需自定义传输。
• 使用基于头的路由进行WAF和限流。Mcp-Method和Mcp-Name头让你的网关在不解析JSON正文的情况下进行路由和授权。

路线图展望：五个优先领域

8月22日路线图定义了下一规范周期的方向。本教程涵盖生产就绪部分；路线图指出了接下来的内容：

优先领域	状态	教程覆盖
代理身份和企业级安全	进行中 (DPoP, WIMSE, EMA)	第5步 — 基线已建立；完整实现待规范定稿
HTTP原生传输统一	已发布(远程)，进行中(本地)	第3步 — 远程HTTP为生产；本地Streamable HTTP over stdio为路线图目标
代理消息原语	扩展发布中 (Tasks, 订阅)	未覆盖 — 服务器发起事件 (webhooks, channels) 为下一前沿
改进的原语(渐进式发现)	设计阶段	第6步 — 模式今天可用discover_tools实现；规范级支持即将到来
改进的SDK开发者体验	已发布 (SDK v2, 一致性测试)	第1步 — SDK v2为当前生产基线

路线图是方向，而非兼容性承诺。7月28日规范已交付无状态HTTP核心和Tasks扩展。推送事件、统一发现、委托和跨SDK一致性仍需实现工作。对于B2B部署，代理身份优先级是值得关注的 — 它解决了MCP安全文章和治理检查清单一直在指出的确切缺口（API密钥和长期令牌）。

教程的生产路径涵盖五步生产检查清单：

相关阅读

• MCP 2026-07-28：无状态协议对B2B代理部署的意义 — 深入讲解无状态协议、显式句柄模式和弃用的配套分析
• MCP Module Code Standard — 使每个模块生产就绪的结构模式：目录结构、工具注册、错误处理、速率限制和审计日志
• MCP Security Hardening Checklist：1,467个暴露服务器及关闭它们的控制 — 在生产前验证服务器的12项控制，解决82%路径遍历和8.5% OAuth缺口

构建小故事

一家运行NetSuite的中型分销商想给销售团队一个AI助手，可以搜索供应商目录、生成报价和检查库存水平，而无需离开CRM。第一次尝试使用了在所有代理实例间共享的单个API密钥 — 91.5%跳过OAuth的MCP服务器。供应商价格表更新在日志文件中暴露了密钥，团队花了两天时间在15个服务中轮换凭证。

重建遵循本教程的生产路径：SDK v2 with类型化工具模式、轮询负载均衡器后的Streamable HTTP传输、15分钟过期的DPoP绑定OAuth令牌、五步报价工作流的显式句柄以及每个服务器实例的OS级沙箱化。代理通过遵循代码标准的MCP模块连接到NetSuite，渐进式发现首先暴露8个目录工具，仅在工作流需要时才扩展到定价和库存。六个服务器实例在负载均衡器后无状态运行。无共享会话存储。无粘性会话。每个请求携带其句柄、令牌和协议版本。

请求范围明确的构建

一周发现。你获得系统清单、工作流地图和固定范围 — 无论你是否与我们合作构建。