如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

MCP 連線

從 OpenAI 或你的環境連線至 MCP 伺服器。

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
}
Agents API 服務連線至遠端 MCP 伺服器,向伺服器發出呼叫並接收結果。若已附加憑證庫,憑證庫會提供與伺服器 URL 相符的憑證。

從你的環境建立連線

執行器會從工作階段的環境建立 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:

執行用來查詢客戶資料的 MCP 伺服器
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 設為現有目錄的絕對路徑。

相關指南

  • 外掛程式可將 MCP 設定與技能打包,供不同工作階段重複使用。
  • 工具搜尋說明如何在支援這項功能的模型和供應商上自動探索 MCP 工具。