MCP 实战：在 OpenAI Agents SDK 中接入外部工具

什么是 MCP：让 Agent 调用任意外部工具

MCP（Model Context Protocol，模型上下文协议）的核心价值，在于让 AI Agent 能够跨程序、跨计算机地使用工具。换句话说，Agent 不再局限于内置能力，而是在连接到一个 MCP 服务器之后，自动发现并调用该服务器暴露的工具。

这篇内容基于一位 YouTube 创作者的 OpenAI Agents 系列教程，演示了如何构建一个 MCP 服务器、如何把它挂载到 Agent 上，并通过多种传输模式进行连接。整个过程以一个趣味化的「隐藏村忍者注册表」为例，直观展示了工具注册、调用与过滤的完整链路。

简单来说，MCP 的工作流程是：先搭建一个 MCP 服务器 → 服务器提供若干工具 → 把服务器传给 OpenAI Agents SDK 创建的 Agent → Agent 根据用户查询自动访问并调用这些工具。

MCP 由 Anthropic 于 2024 年 11 月发布，是一个开放标准协议，旨在解决 AI Agent 与外部工具、数据源之间的碎片化集成问题。在 MCP 出现之前，每个 Agent 框架都需要为每种工具单独编写集成代码，形成大量重复且不可复用的「M×N」集成矩阵。MCP 通过统一的客户端-服务器架构将其简化为「M+N」：任何支持 MCP 协议的 Agent（客户端）都可以直接连接任何 MCP 服务器，无需额外适配。MCP 服务器除了暴露「工具（Tools）」之外，还可以暴露「资源（Resources）」（供读取的数据）和「提示词模板（Prompts）」，构成一套完整的上下文注入机制。目前主流的 AI 编辑器（如 Cursor、Claude Desktop）均已支持 MCP，生态正在快速扩张。

构建一个最小化的 MCP 服务器

搭建 MCP 服务器的第一步，是从 mcp.server.fastmcp 导入 FastMCP，并实例化一个服务器对象，赋予它一个名称（示例中为 hidden leaf ninja registry）。

有了服务器对象后，把工具注册进去非常直观：任何一个普通的 Python 函数，只要在上方加上 @server.tool 装饰器，就会被转换为一个 Agent 可以调用的工具。

示例中注册了两个工具：

• get_ninja_rank(ninja_name: str)：根据忍者名字查询等级，Naruto Uzumaki 与 Sasuke Uchiha 返回 S，其余返回 unknown。
• check_mission_status(mission_id: str)：查询任务状态，返回危险等级，后续会被用作「工具过滤」的演示对象。

这里有一个容易被忽视但极其关键的细节——docstring（文档字符串）。工具的 docstring 不是可有可无的注释，它会被 Agent 用来理解这个工具的用途。写清楚 docstring，Agent 才能判断何时该调用哪个工具。

服务器的运行方式由命令行参数决定：如果传入 http 参数，服务器会以 streamable-http 模式运行（类似一个 REST API 服务器，绑定到 127.0.0.1 与指定端口）；如果没有参数，则以 stdio（标准输入输出）模式作为本地静态服务器运行。

实现上，作者用 tempfile 创建了一个前缀为 ninja_mcp_ 的临时目录，在其中写入一个 ninja_mcp_server.py 文件，把上面的代码字符串写进去，再把该文件路径作为参数传递，供后续连接使用。

三种连接方式：stdio、streamable HTTP 与 Hosted MCP

OpenAI Agents SDK 提供了多种方式连接 MCP 服务器，核心是两种传输模式加一种托管方案。

stdio 模式：同机本地连接

当 MCP 服务器和 Agent 运行在同一台机器上时，使用 MCPServerStdio 最为合适。通过上下文管理器初始化服务器，传入命令和参数（即前面生成的脚本路径），即可把它作为 server 使用。

不经过 Agent 直接调用工具的方式也很简单：await server.call_tool('get_ninja_rank', {...}) 就能拿到工具返回的文本内容。示例中直接调用返回了 text 为 s 的结果，验证工具正常工作。

streamable HTTP 模式：跨网络连接

如果 MCP 服务器部署在另一台服务器上，而 Agent 在别处运行，就需要走网络连接。做法是用 subprocess.Popen 在后台以 http 模式启动服务器（示例端口 8991），把标准输出与标准错误重定向到 subprocess.DEVNULL 以避免输出干扰，再短暂 sleep 等待服务就绪。

随后通过 MCPServerStreamableHttp 并传入 URL（如 http://127.0.0.1:8991/mcp）即可访问。连接成功后同样能列出工具、调用工具并查看返回内容，验证了跨网络模式的可用性。

Hosted MCP：由 OpenAI 服务器代为连接

第三种是 Hosted MCP Tool。它的特点是让 OpenAI 自己的服务器去连接 MCP 服务器，而不是由你的本地程序去连接。配置时可以设置工具调用的审批策略（例如是否在每次工具调用前需要人工确认，示例中设置为跳过人工审批、直接调用）。

在一个真实示例中，作者用 Hosted MCP 连接了一个 live 的 Git MCP 服务器，向 Agent 提问「这个仓库是关于什么的」。Agent 经过工具调用后返回：该仓库包含 OpenAI Codex CLI，一个基于 Rust 的命令行编码 Agent，支持交互与非交互工作流、代码执行、沙箱、审批、配置与可扩展性。这说明 Hosted MCP 在真实场景下确实能跑通。

这三种连接方式本质上对应不同的**传输层（Transport）**实现。stdio 模式通过操作系统的标准输入/输出流进行进程间通信，延迟极低但仅限同机使用；streamable HTTP 模式基于 HTTP 协议，支持服务端流式推送（Server-Sent Events），使得长时间运行的工具调用可以持续返回进度而不阻塞；Hosted MCP 则将连接管理完全委托给 OpenAI 的基础设施，客户端只需声明目标 MCP 服务器的 URL，OpenAI 服务器负责维护实际的 TCP 连接与会话状态，这对需要跨多用户共享同一 MCP 服务器的生产场景尤为有价值。选型时除了考虑部署位置，还需关注安全边界——stdio 的攻击面仅限本机，而 HTTP 模式则需要额外考虑认证与传输加密。

工具过滤：精确控制 Agent 能用什么

MCP 一个实用的能力是工具过滤（tool filter）。你可能不希望 Agent 访问服务器暴露的全部工具，这时可以在连接时传入过滤参数。

示例中，当对 check_mission_status 做了过滤后，Agent 列出的可用工具就只剩 get_ninja_rank 一个。随后分别测试两个问题：

• 「Naruto Uzumaki 的等级是什么」——触发 get_ninja_rank，返回 rank S。
• 「Mission 07 的状态如何」——由于该工具被过滤，Agent 回复「只能查询忍者等级，无法访问任务状态」。

值得关注的一个实践细节是：在未过滤工具的情况下，Agent 有时仍不会主动调用 check_mission_status。作者发现，当查询语句没有明确指向工具时，Agent 可能无法准确理解该用哪个工具。把问题改成「what is the status of mission 7, use the check mission status tool」后，Agent 才正确触发工具调用，返回「mission 07 is danger level 9, evacuate immediately」。

这揭示了一个关键点：工具调用的触发高度依赖查询措辞与工具描述的匹配度。过滤掉的工具 LLM 根本看不到，因为它们不会出现在 MCP 服务器暴露的列表中；而即便工具存在，模糊的查询也可能导致 Agent 不去调用。

工具过滤在安全性与成本控制上都有实际意义。从安全角度看，暴露给 Agent 的工具越少，因提示注入（Prompt Injection）或误判触发高危操作的风险就越低——例如删除数据、发送邮件等不可逆操作应仅在明确需要时才纳入工具集。从成本角度看，LLM 每次推理时都需要将所有可用工具的描述作为上下文传入，工具数量越多，消耗的 Token 就越多；精简工具列表能够直接降低每次调用的费用。工具过滤也是实现「最小权限原则」的重要手段：不同的用户角色或业务场景可以动态加载不同的工具子集，而无需为每种场景单独部署一个 MCP 服务器。

小结：两种模式的选用建议

把 MCP 服务器集成进 OpenAI Agents SDK 的路径已经相当清晰。连接方式的选择主要看部署形态：

• stdio（标准输入输出）：当 MCP 服务器与 Agent 在同一系统时使用，适合本地开发与调试。
• streamable HTTP：当 MCP 服务器部署在远端、Agent 在别处运行时使用，像调用 REST API 一样跨网络访问。
• Hosted MCP：由 OpenAI 服务器代为连接，省去本地程序主动连接的负担。

再配合工具过滤与清晰的 docstring，就能精确地控制 Agent 的能力边界。对于想要让 Agent 接入外部系统的开发者而言，MCP 提供了一套标准化、可组合的接入范式。