结论先说
- Agents SDK 原生支持挂载多台 MCP 服务器。只需实例化对应的传输客户端并传入
Agent的mcpServers数组,SDK 会在运行前自动拉取tools/list并翻译成模型可调用的函数定义。 - 本机命令行进程用
MCPServerStdio,远程 HTTP 服务用MCPServerStreamableHttp。官方推荐新建远程 MCP 优先采用 Streamable HTTP 协议,旧版纯 SSE 服务则使用兼容类MCPServerSse。 - 生产环境务必开启
cacheToolsList: true。默认情况下每次run()都会向 MCP 服务器重新查询一次全量工具元数据;开启缓存可省去重复网络或进程间通信开销。 - 必须成对管理
connect()与close()生命周期。忘记关闭连接会导致 Node.js 或 Python 主进程挂起无法退出,甚至在容器内堆积僵尸子进程。 - 在本地交互调试同款 MCP 工具生态时,国内缺少境外信用卡的用户可在本站自助开通 ChatGPT Plus 或高配额 ChatGPT Pro 搭配 Codex CLI 使用,多人团队可咨询 ChatGPT Business 团队定制。

图:本站根据 OpenAI Agents SDK MCP 官方文档 整理的示意图
本文根据 OpenAI Agents SDK 官方文档《Model Context Protocol (MCP)》与《Agents SDK Guide》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 正在使用 OpenAI Agents SDK(TypeScript 或 Python),想直接复用社区现成的文件系统、GitHub、数据库等 MCP 服务器而免去手写
tool胶水代码的开发者; - 分不清
MCPServerStdio、MCPServerStreamableHttp与云端 Hosted MCP 三种接入方式该怎么选的人; - 发现智能体每跑一轮都变慢一截,需要开启
cacheToolsList缓存工具列表并妥善回收子进程连接的工程师。
一、三种 MCP 接入架构怎么选
对比在终端客户端里静态配置 MCP(如 Codex 配置方法见 /guides/codex-mcp-config),在 Agents SDK 代码中共有三种挂载形态:
| 接入形态 | 谁发起工具网络请求 | 优势与适用边界 |
|---|---|---|
MCPServerStdio | 你的应用本机拉起子进程 | 可直接读写本机目录或内网资源,适合桌面端、CLI 或单机容器 |
MCPServerStreamableHttp | 你的后端服务请求远程 MCP | 支持注入企业内网鉴权 Header,适合微服务架构共享内部工具网关 |
hostedMcpTool(托管模式) | OpenAI 云端直接请求公网 MCP | 无需经过你的应用后端中转,但要求 MCP 地址公网可达 |
二、TypeScript 代码实战:同时接入 Stdio 与 Streamable HTTP

图:本站根据 OpenAI Agents SDK MCP 官方文档 整理的示意图
下面以 @openai/agents 为例,演示同时挂载一个本地文件系统 MCP 服务器和一个带 Bearer 鉴权的远程 Streamable HTTP 服务器,并启用工具缓存:
typescript
import {
Agent,
run,
MCPServerStdio,
MCPServerStreamableHttp,
} from '@openai/agents';
async function main() {
const localFsServer = new MCPServerStdio({
name: 'Local Filesystem',
fullCommand: 'npx -y @modelcontextprotocol/server-filesystem ./docs',
cacheToolsList: true,
});
const remoteDocServer = new MCPServerStreamableHttp({
name: 'Internal Wiki MCP',
url: 'https://mcp.internal.example.com/mcp',
requestInit: {
headers: { Authorization: `Bearer ${process.env.MCP_TOKEN}` },
},
cacheToolsList: true,
});
await localFsServer.connect();
await remoteDocServer.connect();
try {
const assistant = new Agent({
name: 'Doc Assistant',
instructions: '先查内部 Wiki 规范,再核对本地 ./docs 目录下的文档差异并输出中文摘要。',
mcpServers: [localFsServer, remoteDocServer],
});
const res = await run(assistant, '检查发版文档是否符合最新规范');
console.log(res.finalOutput);
} finally {
await localFsServer.close();
await remoteDocServer.close();
}
}
main();
若使用 Python 版 openai-agents,对应类名一致(MCPServerStdio、MCPServerStreamableHttp),放在 async with 上下文管理器内即可在退出代码块时自动执行关闭释放。
订阅与账号准备提示:自己写完自定义 MCP Server 后,先挂载到 Codex CLI 或 Claude Code 做交互联调比直接跑脚本更快发现描述歧义。国内用户可在本站选购 ChatGPT Plus 会员、升级 ChatGPT Pro 充值,或了解 Claude Code 订阅服务。
三、工具缓存失效刷新与常见排障
- 动态工具更新后手动清缓存:开启
cacheToolsList: true后,如果远程 MCP 服务器在运行期按权限动态增删了工具,调用await remoteDocServer.invalidateToolsCache()即可在下一轮强制重新拉取。 - 多台 MCP 出现同名工具冲突:当两台服务器都暴露了名为
search的工具时,模型调用路由会报错或串台。建议在自研 MCP 侧加上业务域名前缀(如wiki_search、fs_search),或使用 SDK 提供的工具过滤配置只放行所需工具。 - 本机 Stdio 启动超时或找不到
npx:守护进程(如 systemd 或 PM2)环境变量里的PATH往往不包含 Node 版本管理器目录,建议在命令中写明可执行文件的绝对路径,API 基础鉴权与函数调用排错也可参考 /guides/openai-api-function-calling 与 /guides/openai-api-error-codes。
常见问题
问:长驻 Web 服务(比如 Express / Fastify)里应该每次请求都 connect 和 close 吗?
答:对于无状态的公共远程 MCPServerStreamableHttp,可在服务进程启动时建立长生命周期实例并开启 cacheToolsList,在进程收到退出信号(SIGTERM)时统一 close;若每个用户的鉴权 Token 不同,则按会话隔离实例并设置空闲回收。
问:MCP 服务器返回超大文本把模型上下文撑爆怎么办?
答:MCP 工具返回值会原样拼入对话历史(超长报错参见 /guides/openai-responses-api),务必在 MCP 服务端对列表查询做分页和字数截断,避免一次返回整张大表。
问:国内没有外币卡,或者公司需要开增值税发票报销,怎么开通配套的官方会员?
答:可通过本站 AI 会员充值总览 选购 ChatGPT Plus 或 ChatGPT Pro,支持支付宝、微信支付及 AlipayHK,支持卡密自助兑换与企业定制,并可开具增值税发票。实时价格以页面显示为准;售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。
相关教程
- Codex MCP 服务器怎么配置与登录
- OpenAI API 函数调用(function calling)怎么写
- OpenAI Responses API 与工具调用机制
- OpenAI API 常见错误码排查指南
参考资料
- OpenAI Agents SDK TypeScript 文档:MCP — https://openai.github.io/openai-agents-js/guides/mcp/
- OpenAI Agents SDK Python 文档:MCP — https://openai.github.io/openai-agents-python/mcp/
- OpenAI API 官方文档:Agents SDK — https://platform.openai.com/docs/guides/agents-sdk
0 条评论
还没有评论,来抢沙发~