結論先說
- 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 條評論
還沒有評論,來搶沙發~