OpenAI Agents SDK 接入本地与远程 MCP 服务器怎么写:MCPServerStdio、MCPServerStreamableHttp 与工具缓存

怎么在 OpenAI Agents SDK 里挂载现成的本地与远程 MCP 工具服务器?本文按官方文档整理 MCPServerStdio、MCPServerStreamableHttp 连接与释放写法,以及 cacheToolsList 工具缓存优化。

NNathaniel bigo··原创首发·AI 辅助撰写
9 分钟读完
资料核对于 2026-11-18 · 依据官方文档与公开资料整理 其他 账号

结论先说

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

Agents SDK 本地与远程 MCP 对比

图:本站根据 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

Agents SDK 挂载 MCP 四步标准流程

图:本站根据 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 订阅服务。

三、工具缓存失效刷新与常见排障

  1. 动态工具更新后手动清缓存:开启 cacheToolsList: true 后,如果远程 MCP 服务器在运行期按权限动态增删了工具,调用 await remoteDocServer.invalidateToolsCache() 即可在下一轮强制重新拉取。
  2. 多台 MCP 出现同名工具冲突:当两台服务器都暴露了名为 search 的工具时,模型调用路由会报错或串台。建议在自研 MCP 侧加上业务域名前缀(如 wiki_search、fs_search),或使用 SDK 提供的工具过滤配置只放行所需工具。
  3. 本机 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,支持卡密自助兑换与企业定制,并可开具增值税发票。实时价格以页面显示为准;售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。

相关教程

参考资料

  • 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

Nathaniel 的更多内容

  1. 01

    独立开发者用 ChatGPT + Codex 跑通产品全流程:市场验证、PRD、原型到代码上线复盘清单

    单人做独立产品最容易陷入「闭门写两个月代码上线零用户」或「AI 写到一半目录越改越崩」。本文整理「ChatGPT 负责市场验证、PRD 与复盘 + Codex 负责工程实现与测试」的五阶段双轨流程,附起手提示词与 7 项上线复盘清单。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成规范文件命名规则、整理混乱目录树与合并零散发票抬头清单脚本

    面对满桌面的「新建文件夹」「最终版2」和上百张零散电子发票,手工改名抄台账耗时又容易漏重。本文分享先脱敏取样、再用 ChatGPT 生成带预演和回滚日志的本地 Python 脚本,离线安全完成目录整理与发票抬头合并去重的实战流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外邮件营销(EDM)受众分层文案、A/B 主题行测试与防进垃圾箱自检

    做海外独立站或出海 SaaS 邮件营销(EDM),最怕千人一面群发被直接送进垃圾箱。本文结合 Gmail/Yahoo 批量发件人规范,梳理用 ChatGPT 设计受众分层文案、批量生成 A/B 主题行矩阵并开展发前垃圾词与合规自检的实战提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写 Notion Formula 2.0 公式、Obsidian Dataview 查询与 Airtable 自动化脚本

    给 Notion 数据库写多条件 Formula 2.0 公式、给 Obsidian 写 Dataview 动态看板,或在 Airtable 里写自动化脚本,经常因为一个小括号或类型不匹配报错半天。本文整理三大工具的通用上下文喂料规范与三套直接可复制的生成提示词。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 处理复杂 JSON / YAML / XML 字段映射、格式转换与校验规则编写实战

    对接第三方 API、迁移 Kubernetes 配置或解析政企 XML 报文时,手工对照几百行嵌套字段既慢又容易漏掉空值与类型边界。本文整理用 ChatGPT 完成字段映射表梳理、生成确定性转换脚本以及编写 JSON Schema / Pydantic / XSD 校验规则的实战流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 准备本科/硕士毕业论文答辩:提炼答辩 PPT 结构、模拟导师犀利追问与 3 分钟自述稿

    毕业论文写完后,要在 3–5 分钟内讲清研究价值并顶住答辩评委的连环追问并不轻松。本文整理在严格遵守高校学术规范的前提下,用 ChatGPT 提炼答辩 PPT 结构、打磨 3 分钟口语自述稿并开展模拟导师犀利追问的排练流程与提示词。

    ChatGPT0

同模型

  1. 01

    从免费试水到全职写码:Codex 个人开发者月度额度规划与 Plus / Pro 5x / Pro 20x 升级时机指南

    个人开发者用 Codex 写代码,怎么判断自己该留在 Plus、买 Credits 点数兜底,还是升级 Pro 5x(官方 Pro 100)或 Pro 20x(官方 Pro 200)?本文基于官方定价规则与 /status 预警信号,给出清晰月度额度规划。

    ChatGPTCodex0
  2. 02

    小微研发团队在 ChatGPT Business 与 Pro 之间怎么配 Codex 席位最省钱:角色分层与额度测算

    5 到 20 人的小微研发团队采购 Codex,全员上高配太贵、全员买基础档又天天卡 5 小时限流?本文对照官方 Business(Standard / Premium)与 Pro 规则,给出按角色分层的席位搭配与预算测算框架。

    ChatGPTCodex0
  3. 03

    ChatGPT + Codex 联合开发 SaaS MVP 实战:先写 PRD 与架构图再落库写代码

    直接让 AI 一口气从零写完 SaaS 往往表结构混乱、功能返工。本文拆解 ChatGPT 写 PRD 与架构图、落盘仓库文档与 AGENTS.md、再由 Codex 分片落库与测试验收的完整闭环。

    ChatGPTCodex0
  4. 04

    ChatGPT 智能交互界面(Intelligent UI)怎么触发和用好:表单、计算器、图表与对比卡片实战

    同样是用 GPT-6,为什么别人的 ChatGPT 能直接弹出带滑块的计算器、交互图表和对比卡片,你的却只回一大段纯文字?本文依据 OpenAI GPT-6 官方文档讲清触发前提、4 类高命中提问模板,以及不出交互界面时的排查方法。

    ChatGPT0
  5. 05

    买 ChatGPT Pro 5x 还是 Pro 20x 怎么按月度用量自测:Codex 并发与深度研究频次估算对照

    犹豫买 ChatGPT Pro 5x(官方 Pro 100)还是 Pro 20x(官方 Pro 200)?本文对照官方最新档位规则,用 Codex 并发任务、Fast 模式消耗倍率和深度研究频次三项指标帮你做月度用量自测。

    ChatGPTCodex0
  6. 06

    Codex 额度消耗太快怎么省:模型档位切换、推理强度降级、关闭非必要 Fast 模式与控上下文 6 招

    刚写半天代码就提示 Codex 触达周期限额?本文从 Token 计费原理拆解消耗黑洞,给出模型降档、推理强度调优、关闭非必要高速模式与控上下文的 6 招省额度方案。

    ChatGPTCodex0

同产品的其他教程

  1. 01

    用 ChatGPT 整理家庭装修预算明细、隐蔽工程验收清单与主材优缺点对比表实战

    第一次装修面对几十页施工报价单、密密麻麻的水电防水隐蔽项目与五花八门的主材参数,极易踩坑增项。本文梳理用 ChatGPT 审查装修报价漏项、生成带公式的预算明细表、定制工地隐蔽工程验收单与主材对比表的实战提示词。

    ChatGPT0
  2. 02

    用 ChatGPT 做费曼学习法读书共读:反向追问检验自己是否真读懂专业书籍与整理书单笔记

    读完一本专业硬书常感觉「合上书就忘」,直接让 AI 概括全书又容易产生懂了的错觉。本文介绍用 ChatGPT 结合 Study Mode 与费曼学习法做反向追问共读,通过通俗复述、挑刺盲区到沉淀书单卡片的完整流程与提示词。

    ChatGPT0
  3. 03

    用 ChatGPT 做外贸产品多语种目录、展会邀约与客户跟进节奏表(附脱敏与本地化提示词)

    做外贸展会与海外推广时,手工翻译十几款产品目录费时且容易留下一堆中式英文,展后客户跟进也常缺节奏。本文梳理用 ChatGPT 先脱敏建术语库、再批量产出多语种目录、展前邀约函与展后 21 天跟进节奏表的实战流程与提示词。

    ChatGPT0
  4. 04

    用 ChatGPT 写高质量技术专栏文章、开源项目 Release Notes 与版本更新日志实战

    让 AI 直接凭空写技术文章容易满篇空洞套话,直接甩 Git 记录写更新日志又常常漏掉破坏性变更。本文整理用 ChatGPT 结合真实代码片段、压测数据与 PR 摘要,高效产出深度技术专栏、GitHub Release Notes 与 CHANGELOG 的实战工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做产品用户访谈纪要编码、提炼高频痛点需求池与 RICE 优先级打分实战

    手头攒了十几份用户访谈逐字稿,手工贴便利贴归纳痛点耗时又容易带入主观偏见。本文分享用 ChatGPT 完成脱敏检查、逐份开放式编码、跨样本聚类高频痛点并搭建 RICE 优先级打分表的 5 步实战流,附可直接复制的三段核心提示词。

    ChatGPT0
  6. 06

    ChatGPT 网页版上传超过 10 个文件或回形针附件按钮变灰怎么办:打包合并与配额限制排查

    在 ChatGPT 网页版批量分析文档时,常遇到一次选超 10 个文件被拦截或输入框回形针按钮变灰。本文依据 OpenAI 文件上传与存储说明,梳理 6 类常见报错的分流排查法,提供 ZIP 打包、本地合并与 Projects 复用方案及可直接复制的解包提示词。

    ChatGPT0

0 条评论

登录 后参与评论

还没有评论,来抢沙发~