MCP 伺服器會發布工具定義並執行工具呼叫。Agents API 會探索可用工具、呼叫伺服器，並將結果傳回智慧體。你的應用程式不需要逐一處理每次呼叫。
依據哪些位置能連上伺服器，選擇從哪裡建立連線：
| 連線 | 執行位置 | 是否需要環境 |
|---|---|---|
使用 connection_origin: "service" 的 HTTP 連線（預設） | OpenAI | 否 |
使用 connection_origin: "environment" 的 HTTP 連線 | 你的工作階段環境 | 是 |
| 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。工具會傳回使用 pro 方案的 Example Customer。
對於由 OpenAI 託管的 stdio MCP，請省略網路政策，或將其設為 enabled。這類連線不支援 disabled 和 restricted 網路政策。
新增身分驗證
若伺服器允許匿名存取，請省略身分驗證欄位和 vault_ids。否則，請為連線選擇憑證來源：
- 單一工作階段的 HTTP 憑證： 建立工作階段時，設定
transport.authorization或transport.headers。Agents API 會將這些值加密，且不會將其包含在傳回的工作階段資源中。 - 可重複使用的 HTTP 憑證： 將憑證儲存在保管庫中，並透過
vault_ids附加保管庫。保管庫僅適用於從 OpenAI 建立的連線。憑證會依伺服器 URL 進行比對；若有多個憑證相符，請使用credential_id選擇其中一個。 - Stdio 憑證： 在環境中提供憑證值，並在
transport.env_vars中列出對應的環境變數名稱。在環境中執行的程式碼可以讀取這些值。自行託管的工作階段不接受直接在transport.env中設定的值。
例如，HTTP 傳輸可以包含 Bearer Token 和另一個標頭：
{
"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 組態欄位，請參閱建立工作階段參考資料。
排解連線問題
如果必要的伺服器無法初始化，請查看 agent.session.turn.failed 中的錯誤。若使用 stdio 伺服器，也請檢查 MCP 程序記錄。
- 網路存取： 檢查 URL 和
connection_origin。若從環境建立連線，請確認執行器已連線，且其網路能連上伺服器。 - 憑證： 檢查 Token 或標頭。若使用保管庫，請確認憑證與伺服器 URL 相符。
- 執行檔與相依套件： 確認所設定的指令能在環境中執行。
- 工作目錄： 直接設定 stdio 組態時，請將
cwd設為現有目錄的絕對路徑。