MCP 伺服器會發布工具定義,並執行工具呼叫。Agents API 會探索可用工具、呼叫伺服器,再將結果傳回智慧體。你的應用程式無須逐一處理這些呼叫。
請根據哪些位置可以存取伺服器,選擇從哪裡建立連線:
| 連線方式 | 執行位置 | 是否需要環境 |
|---|---|---|
HTTP,使用 connection_origin: "service"(預設) |
OpenAI | 否 |
HTTP,使用 connection_origin: "environment" |
工作階段的環境 | 是 |
| stdio | 工作階段環境中的程序 | 是 |
從 OpenAI 建立連線
將使用 HTTP 的 MCP 伺服器加入 agent.tools。OpenAI 必須能連線至該伺服器。無論工作階段是否有環境,都可以使用這種連線方式。
例如,OpenAI 文件的 MCP 伺服器允許匿名存取:
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp"
},
"connection_origin": "service",
"required": true
}

從你的環境建立連線
執行器會從工作階段的環境建立 MCP 連線。如果伺服器位於私有網路,或要使用的軟體安裝在該環境中,請使用這種連線方式。
將工作階段的 environment.type 設為 self_hosted 或 openai_hosted。如果是自行託管的環境,請在智慧體使用工具前連接執行器。
透過 HTTP 連線
如果伺服器已在執行,請使用 HTTP。將下列項目加入 agent.tools,並將 URL 換成你的環境可以連線的位址:
{
"type": "mcp",
"server_label": "internal_search",
"transport": {
"type": "http",
"server_url": "https://mcp.internal.example.com/search"
},
"connection_origin": "environment",
"required": true
}
在這種設定下,localhost URL 指向工作階段的環境。如果省略 connection_origin,則會由 OpenAI 建立連線。
使用 stdio 啟動伺服器
使用 stdio 可讓執行器啟動伺服器程序。請先在環境中安裝伺服器及其相依套件。
在這個查詢客戶資料的範例中,請先安裝 MCP SDK:
python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'
將伺服器程式儲存為 /workspace/lookup_mcp.py:
import sys
from mcp.server.fastmcp import FastMCP
server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)
@server.tool()
def get_customer(customer_id: str) -> dict:
"""Look up a customer in the example data."""
customers = {"123": {"name": "Example Customer", "plan": "pro"}}
return {"customer": customers.get(customer_id)}
if __name__ == "__main__":
transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
server.run(transport=transport)將伺服器加入 agent.tools。stdio 引數會指定指令碼使用的傳輸方式:
{
"type": "mcp",
"server_label": "customer_lookup",
"transport": {
"type": "stdio",
"command": "/workspace/mcp-demo/bin/python",
"args": ["/workspace/lookup_mcp.py", "stdio"],
"cwd": "/workspace"
},
"required": true
}
使用 stdio 時,必須設定 command,並為 cwd 指定絕對路徑。args 為選填。請省略 connection_origin。
傳送訊息,請智慧體查詢編號為 123 的客戶。工具會傳回客戶名稱 Example Customer,其方案為 pro。
如果 stdio MCP 伺服器由 OpenAI 託管,請省略網路政策,或將其設為 enabled。這類連線不支援 disabled 和 restricted 網路政策。
加入驗證設定
如果伺服器允許匿名存取,請省略驗證欄位和 vault_ids。否則,請為連線選擇憑證來源:
- 單一工作階段使用的 HTTP 憑證: 建立工作階段時,設定
transport.authorization或transport.headers。Agents API 會將這些值加密,並在傳回的工作階段資源中省略這些值。 - 可重複使用的 HTTP 憑證: 將 MCP 憑證儲存在憑證庫中,並透過
vault_ids將憑證庫附加至工作階段。只有從 OpenAI 建立的連線才能使用憑證庫進行 MCP 驗證。系統會依伺服器 URL 比對憑證。如果有多個憑證相符,請使用credential_id指定其中一個。 - stdio 憑證: 在環境中設定變數值,並在
transport.env_vars中列出變數名稱。在環境中執行的程式碼可以讀取這些值。自行託管的工作階段不接受直接寫在transport.env中的值。
例如,HTTP 傳輸設定可以包含 Bearer 權杖及另一個標頭:
{
"type": "http",
"server_url": "https://mcp.example.com/mcp",
"authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
"headers": { "X-Tenant-ID": "tenant_123" }
}
請為 Authorization 選擇單一來源:直接在設定中指定,或使用憑證庫中相符的憑證。使用憑證庫驗證時,仍可設定其他標頭。從環境建立的 HTTP 連線不會使用憑證庫中的憑證,請直接在設定中提供驗證資訊,或使用受信任的代理伺服器。
請勿將機密資訊寫入可重複使用的智慧體定義、外掛程式封存檔或記錄中。若要避免智慧體產生的程式碼存取憑證,請使用受信任的代理伺服器或其他伺服器,由其在環境外提供憑證。
控制工具存取權與啟動行為
設定 allowed_tools 可限制智慧體能探索及呼叫哪些工具。設定 required: true 後,如果伺服器無法初始化,該回合就會失敗。依預設,即使伺服器無法初始化,回合仍可繼續執行。
如需查看所有 MCP 設定欄位,請參閱建立工作階段的 API 參考文件。
排解連線問題
如果必要的伺服器無法初始化,請查看 agent.session.turn.failed 中的錯誤。若使用 stdio 伺服器,也請檢查 MCP 程序的記錄。
- 網路存取: 檢查 URL 和
connection_origin。若從環境建立連線,請確認執行器已連線,且執行器所在的網路可以存取伺服器。 - 憑證: 檢查權杖或標頭。若使用憑證庫,請確認憑證與伺服器 URL 相符。
- 執行檔與相依套件: 確認設定中指定的指令可以在環境中執行。
- 工作目錄: 若直接在設定中指定 stdio 連線,請將
cwd設為現有目錄的絕對路徑。