《AI Agent原理与实战》2026版 第18课 MCP 协议深度实战

本文收录于专栏《AI Agent原理与实战》2026版—— 专栏系统覆盖 AI Agent 的记忆、工具、插件与实战，点击订阅可跟踪后续更新。

本课定位：框架各自为政的时代正在被一个协议终结：MCP。本课从 N×M 集成困境讲到 server/client/transport 架构，亲手写一个订单 API 的 MCP server 并接入 Agent，最后看 WorkBuddy 如何把它分发给全公司——协议课里动手最实的一课。

阶段 3｜框架与协议 ｜ 来源：【微·11 上】

关键字：MCP协议、Model Context Protocol、MCP Server、工具集成、stdio传输、协议架构、企业级分发、WorkBuddy

本节目录

• 18.1 MCP 解决什么问题
• 18.2 架构：server / client / transport
• 18.3 工具发现与 schema 暴露机制
• 18.4 生态现状速览（2026-10 检索）
• 18.5 案例：为"内部订单 API"编写 MCP server 并手工验证【已实测，2026-10-01】
• 18.6 开源 Host 替代：用 Hermes Agent 挂载你的 MCP server【已实测，2026-10-01】
• 18.7 企业侧分发：把 MCP server 交给非技术同事（腾讯 WorkBuddy 路径）【检索验证 2026-10-01，未实测】

概念讲解

18.1 MCP 解决什么问题

MCP（Model Context Protocol，模型上下文协议）是 Anthropic（Claude 系列开发商，全球头部 AI 实验室之一）2024-11 开源的标准协议，2025-12-09 由 Anthropic 捐赠给 Linux 基金会旗下的 Agentic AI Foundation（供应商中立治理）——捐赠一年即成为 AI 工具连接领域的事实标准（ChatGPT、Claude、Cursor、VS Code Copilot 等全面支持）。它解决的是N 个应用 × M 个工具的集成矩阵问题：以前每个 AI 应用接每个数据源都要写一遍胶水代码（N×M），有了 MCP，工具方写一次 server、应用方实现一次 client，集成成本降为 N+M——这就是"AI 界的 USB-C"比喻的来源。截至捐赠公告时官方口径：97M 月度 SDK 下载、10,000 活跃 server。

区分三个角色：

• Host：装在用户侧的 AI 应用（Claude Desktop、Hermes、Cursor、VS Code 等），内含 MCP client。
• Client：Host 内部与单个 server 的连接实例（协议状态机）。
• Server：暴露工具/资源/提示词的进程，可以是本地进程也可以远程服务。

18.2 架构：server / client / transport

微软课程思想（源自微软原课第 11 课《Using Agentic Protocols》上半——MCP 部分）：微软把 MCP 定位为"通用适配器（universal adaptor）"——让 Agent 以一致方式连接任意数据源与工具，并给出对比直接调 API 的三大收益：标准化（一套协议接所有源）、解耦（工具方与 Agent 方独立演进）、生态复用（写一次 server 全生态可用）。微软同时提醒：协议带来标准化的同时也带来安全新面（工具描述注入上下文、越权调用），要配合第 25 课的权限分级。本课 18.1-18.4 的架构拆解沿用此框架，案例部分把微软的"配置即接入"示例升级为端到端实测。

MCP 建立在 JSON-RPC 2.0 之上。三种核心原语（server 可暴露的东西）：

两种官方 transport（传输层）：

• stdio：server 是 Host 拉起的本地子进程，stdin/stdout 交换 JSON-RPC。零网络配置，适合本地工具——调试和入门首选。
• Streamable HTTP：server 是 HTTP 服务，支持远程部署、鉴权、多客户端复用（旧版 HTTP+SSE 传输已被此取代）。

生命周期：client 与 server 先交换initialize请求（协商协议版本、能力声明），再发notifications/initialized，之后进入正常消息循环，能力变更可通过notifications/tools/list_changed通知。

SDK 版本大坑（2026-09 起生效，本课实测撞上）：官方 Python SDK 的 1.x 与 2.x 是破坏性变更——pip install mcp今天默认装 2.2.0，其中FastMCP类已改名MCPServer，from mcp.server.fastmcp import FastMCP会直接抛ModuleNotFoundError（2.x 专门写了迁移提示指向官方迁移指南）。对照：

本课代码两种写法都给（先 2.x 当前版，后 1.x 兼容版），老教程/存量代码大量是 1.x 写法，看到报No module named 'mcp.server.fastmcp'就是版本装错了。

18.3 工具发现与 schema 暴露机制

MCP 的"即插即用"关键在发现机制：

1. Host 拉起/连接 server 后调tools/list，server 返回每个工具的name + description + inputSchema（JSON Schema）。
2. Host 把所有已连接 server 的工具 schema注入模型的系统提示/工具列表——模型"看见"工具全靠这一步。
3. 模型决策调用某工具 → Host 发tools/call给对应 server → server 执行 → 结果以 content 块（text/image/resource）回传 → Host 把结果喂回模型。

注意一个工程含义：每多接一个 MCP server，系统提示就膨胀一块——工具描述写得啰嗦，token 成本直接上涨（这是第 13 课上下文工程的协议层体现，也是"不常用的 server 不要常驻连接"的原因）。

18.4 生态现状速览（2026-10 检索）

主流 Host 侧（Claude Desktop、Cursor、VS Code Copilot、Codex/CLI 类、开源桌面 Agent）与 server 生态已成型（官方捐赠公告口径：10,000 活跃 server、97M 月度 SDK 下载，2025-12 数据）；各大框架（LangGraph、OpenAI Agents SDK、MAF、smolagents）都已支持把 MCP server 作为工具源接入。选型实务：优先 stdio 本地跑，需要共享/远程才上 HTTP。

案例实战

18.5 案例：为"内部订单 API"编写 MCP server 并手工验证【已实测，2026-10-01】

运行环境：实测于 Linux（Ubuntu 22.04 / Python 3.10.12）。Windows 复现零障碍：官方 MCP Python SDK 是纯 Python 包（PyPI wheel 为py3-none-any，2026-10-01 核验），Windows PowerShell 下pip install "mcp[cli]"与 Linux 完全一致，server 代码零改动——stdio transport 走标准输入输出，不依赖任何平台特性。无需 API key、无需 Docker。

目标：写一个最小可跑的 stdio MCP server，暴露查订单工具，先手工验证协议链路，再端到端接入真实 Agent（国内模型驱动）。

完整 server 代码（mcp 2.2.0 当前版）：

# MCP server: order_service.py ｜ mcp==2.2.0（2.x 写法）｜ 2026-10-01 实测通过frommcp.server.mcpserverimportMCPServer# 2.x: FastMCP 已改名 MCPServerserver=MCPServer("Order Service")@server.tool()# 必须带括号，裸写 @server.tool 会报 TypeErrordefget_order(order_id:str)->dict:"""按订单号查询订单状态与金额。order_id: 如 'A1001'"""orders={"A1001":{"status":"已发货","amount":299.0},"A1002":{"status":"待支付","amount":1580.0},}returnorders.get(order_id,{"error":f"订单不存在:{order_id}"})@server.tool()defget_logistics(order_id:str)->dict:"""按订单号查询物流轨迹。order_id: 如 'A1001'"""tracks={"A1001":{"carrier":"SF","traces":["10-30 仓库出库","10-31 到达北京分拨"]},}returntracks.get(order_id,{"error":"暂无物流信息"})if__name__=="__main__":server.run()# 默认 stdio transport，Host 以子进程方式拉起

1.x 兼容版（存量代码常见；pip install "mcp<2"后可跑）：

# mcp==1.29.1（1.x 写法）｜ 2026-10-01 实测通过frommcp.server.fastmcpimportFastMCP# 1.x 入口；在 2.x 环境下此行直接 ModuleNotFoundErrormcp=FastMCP("Order Service")@mcp.tool()defget_order(order_id:str)->dict:"""按订单号查询订单状态与金额。order_id: 如 'A1001'"""orders={"A1001":{"status":"已发货","amount":299.0}}returnorders.get(order_id,{"error":f"订单不存在:{order_id}"})if__name__=="__main__":mcp.run()

手工验证（不依赖任何 Host，纯管道）——把 4 条 JSON-RPC 消息按序灌进 server 的 stdin（Linux/macOS 写法）：

printf'%s\n'\'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'\'{"jsonrpc":"2.0","method":"notifications/initialized"}'\'{"jsonrpc":"2.0","id":2,"method":"tools/list"}'\'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_order","arguments":{"order_id":"A1001"}}}'\|python3 order_service.py

Windows PowerShell 等价写法（【未实测】，标准 PS 语法）：

# 逐行写入消息文件再管道给 server（PowerShell 无 printf）$msgs= @('{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}','{"jsonrpc":"2.0","method":"notifications/initialized"}','{"jsonrpc":"2.0","id":2,"method":"tools/list"}','{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_order","arguments":{"order_id":"A1001"}}}')$msgs|python order_service.py

实测输出（mcp 2.2.0，2026-10-01，Ubuntu 22.04 / Python 3.10；tools/call 返回同 1.x 格式）：

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{...,"tools":{"listChanged":false}},"serverInfo":{"name":"Order Service","version":""}}} {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"get_order","description":"按订单号查询订单状态与金额。order_id: 如 'A1001'","inputSchema":{"properties":{"order_id":{"title":"Order Id","type":"string"}},"required":["order_id"],"type":"object"}}]}} {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\n \"status\": \"已发货\",\n \"amount\": 299.0\n}"}],"isError":false}}

三个响应分别对应：① 握手成功且声明了 tools 能力；② 工具发现——get_order的 schema 由函数签名 + docstring 自动生成（与第 7 课手写 JSON Schema 对照，自动化但可控性互换）；③ 工具调用返回订单 JSON。

实测踩到的坑（含 1.x/2.x 差异）：

1. 版本装错直接报 ModuleNotFoundError：在 2.x 环境跑from mcp.server.fastmcp import FastMCP报错并提示"FastMCP was renamed to MCPServer"——先pip show mcp看版本再对号入座（18.2 节对照表）。
2. @server.tool裸装饰器（不带括号）在 1.x 和 2.x 都直接TypeError: Did you forget to call it?。
3. 手工验证时若 JSON 消息本身非法，server 只回一个Internal Server Error通知（stderr 有 pydantic 校验细节）——排查 stdio 问题要看 stderr 而不是 stdout。

接入 Agent 调用——端到端实测【已实测】：openai-agents SDK（0.22.3）拉起上面的 MCP server 作为子进程，模型用 DeepSeek 云 API，一行配置接入：

# openai-agents==0.22.3 + mcp==2.2.0 + DeepSeek ｜ 2026-10-01 实测通过importasyncio,os,sysfromagentsimportAgent,Runnerfromagents.mcpimportMCPServerStdio os.environ["OPENAI_BASE_URL"]="https://api.deepseek.com/v1"# 国内模型端点os.environ["OPENAI_API_KEY"]=os.environ["DEEPSEEK_API_KEY"]asyncdefmain():asyncwithMCPServerStdio(params={"command":sys.executable,# 拉起 server 子进程"args":["order_service.py"],})asserver:tools=awaitserver.list_tools()# 工具发现 (tools/list)print("[发现工具]",[t.namefortintools])agent=Agent(name="客服助手",instructions="你是订单客服。查订单用 get_order 工具。",mcp_servers=[server],model="deepseek-chat")result=awaitRunner.run(agent,"帮我查一下订单 A1001 的状态",max_turns=6)print(result.final_output)asyncio.run(main())

实测输出（2026-10-01，Linux；DeepSeek 云 API）：

[发现工具] ['get_order', 'get_logistics'] 订单 A1001 的信息如下： - **状态**：已发货 - **金额**：299.00 元

全链路：Host 拉起 server 子进程 → initialize → tools/list（Agent 自动发现两个工具）→ 用户提问 → 模型决策调get_order→ tools/call → 结果回传 → 最终回答。MiniMax-M3 同样跑通（改OPENAI_BASE_URL为https://api.minimaxi.com/v1、model 为MiniMax-M3即可，实测输出同样正确）。

国产模型接入的实测差异（呼应第 16 课 16.7 端点表）：

通用 JSON 配置接入（任意支持 MCP 的 Host，如 Claude Desktop 类客户端）：

{"mcpServers":{"order-service":{"command":"python","args":["C:/path/to/order_service.py"]}}}

同一 server 不改一行代码接入所有框架（openai-agents 用MCPServerStdio；LangGraph 用langchain-mcp-adapters；MAF 原生工具发现）——这就是协议价值。

18.6 开源 Host 替代：用 Hermes Agent 挂载你的 MCP server【已实测】

openai-agents 是写代码的 SDK 路线；如果你想要开箱即用的开源 Agent 宿主（自带终端/浏览器/文件工具 + MCP 支持 + 多模型接入），可选完全开源的替代品，代表是Hermes Agent（Nous Research 出品——2023 年由 Teknium 等创立的开源模型团队，以 Hermes 系列开源大模型闻名；其 Agent 框架 MIT 协议，25 万 stars，2026 年活跃度极高）。其他开源选择还有 Flowise（可视化，第 20 课同类）、AgentScope 等。

把上面的 order server 挂进 Hermes 有两条路（Linux/macOS/WSL2 与 Windows 原生均支持，官方一行安装）：

# 0. 安装（Linux/macOS/WSL2；Windows PowerShell 用 install.ps1，见官方文档）curl-fsSLhttps://hermes-agent.nousresearch.com/install.sh|bash# 1. 首选：一条命令完成"连接→发现工具→写配置→启用"hermes mcpaddstage3-order-server\--command/path/to/your/venv/bin/python\--args/path/to/order_service.py# 实测输出（2026-10-01，Linux；交互确认 Enable all? 输入 Y）：# ✓ Connected! Found 1 tool(s) from 'stage3-order-2':# get_order 按订单号查询订单状态与金额。order_id: 如 'A1001'# ✓ Saved 'stage3-order-2' to ~/.hermes/config.yaml (1/1 tools enabled)

mcp add背后做的事：拉起 server 子进程 → initialize 握手 → tools/list 发现 → 交互确认后写入~/.hermes/config.yaml。等效的手工路径（适合脚本化/已有配置仓库）是直接编辑配置：

# ~/.hermes/config.yamlmcp_servers:stage3-order-server:command:/path/to/your/venv/bin/python# 该解释器需 pip install 过 mcp（版本对号 1.x/2.x）args:[/path/to/order_service.py]timeout:60connect_timeout:30enabled:true

# 2. 验证挂载与工具发现（两条路径共用）hermes mcpteststage3-order-server# 实测输出（2026-10-01，Linux）：# ✓ Connected (1048ms)# ✓ Tools discovered: 1# get_order 按订单号查询订单状态与金额。order_id: 如 'A1001'

挂载成功后，对话中 Agent 会自动发现并按需调用get_order——无需写任何胶水代码。实测撞到的坑：server 的command第一次写成系统python3（没装 mcp 2.x）直接启动失败——MCP server 配置里的 command 必须指向装了对应 SDK 版本的解释器，这也是所有 Host 的通病（openai-agents 的sys.executable写法天然规避此坑）。

对比小结：openai-agents 适合把 MCP 工具编进你自己的应用；Hermes 这类宿主适合"把 server 当插件、立刻在对话里用起来"。两者不冲突——同一 server 两种挂法都成立。

换成 HTTP transport只需一行改动：server.run(transport="http", host="0.0.0.0", port=8000)（2.x 的 MCPServer；1.x 的 FastMCP 同参数），适合把内部服务部署成团队共享的远程 server；本地开发保持 stdio 即可。

18.7 企业侧分发：把 MCP server 交给非技术同事（腾讯 WorkBuddy 路径）【检索验证 2026-10-01，未实测】

写好 MCP server 只是第一步；企业里真正的难题是分发给不会配命令行的同事。国内代表路径是腾讯 WorkBuddy（腾讯云产品，原生支持 MCP 接入）：

• 配置方式：WorkBuddy 的 Agent 配置面板直接填 MCP Server 信息（可视化表单/JSON 两种口径，官方文档还演示了自然语言配置），发布时与平台"连接器"合并生效——同事拿到的是 IM 会话里可 @ 的助手，而不是一个命令行工具。
• 托管形态：WorkBuddy Managed Agents（WMA）提供云端托管的智能体运行服务，MCP 调用结果、OAuth、A2A 连接都由平台托管——对应第 27 课"部署"的企业级答案。
• 典型分工：工程师写并维护 MCP server（本课内容）→ 平台管理员在 WorkBuddy 里配置 Agent + 挂载 server → 业务同事在 IM 里使用。工具开发与使用彻底解耦。

这条路径是 MCP"N+M 取代 N×M"价值在企业组织维度的体现：工具方仍只写一次 server，接入侧从"每个应用集成一次"变成"平台配置一次"。

小结

• MCP 用 N+M 取代 N×M 的集成矩阵：工具方写一次 server、应用方实现一次 client。
• 三原语 Tools/Resources/Prompts（控制方分别是模型/应用/用户）；两种 transport：stdio（本地调试首选）与 streamable HTTP（远程共享）。
• 发现机制：initialize 握手 → tools/list → schema 注入模型上下文 → tools/call 执行回传。
• SDK 1.x/2.x 破坏性变更：FastMCP→MCPServer 改名、import 路径全变；先pip show mcp再对号入座，存量 1.x 代码用mcp<2锁版本。
• 端到端实测：openai-agents + 四家国产模型（DeepSeek/MiniMax/GLM/MiMo）全部跑通"发现工具→调用→回答"全链路（Kimi/Qwen 接入参数见第 16 课 16.7）；GLM 无 Responses 端点（404）必须显式 ChatCompletionsModel，MiMo Responses API 已上线（实测 completed）但本课 MCP 链路用 ChatCompletionsModel 跑通。
• 同一个 server 不改代码接入任意支持 MCP 的 Host/框架（Claude Desktop/LangGraph/OpenAI Agents SDK/MAF，以及开源宿主 Hermes Agent——18 课内含 Hermes 三步挂载实测）。
• 实测要点：@server.tool()必须带括号；stdio server 的报错在 stderr；工具描述直接进上下文——写得啰嗦=烧 token。

参见：第 7 课《工具调用模式》（schema 的 API 层原理）、第 8 课《工具设计与 ACI 工程规范》（工具描述质量）、第 13 课《上下文工程》（工具描述的 token 账）、第 19 课《A2A 与 Agent 互操作生态》（MCP 之外的另两个协议）。

扩展阅读

🌐 网络提示：github.com 需代理（clone 可走 ghproxy 加速、push 优先 SSH）；框架文档站（GitHub Pages/Cloudflare）可达性波动，打不开时稍后重试；pip 安装建议加清华镜像-i https://pypi.tuna.tsinghua.edu.cn/simple。详见总纲附录《国内网络访问与国产适配指南》。

• MCP 官方规范：https://modelcontextprotocol.io/
• 官方 Python SDK：https://github.com/modelcontextprotocol/python-sdk
• MCP server 目录：https://github.com/modelcontextprotocol/servers
• 微软原课第 11 课（协议三件套总览）：https://github.com/microsoft/ai-agents-for-beginners/tree/main/11-agentic-protocols

我的专栏