如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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 时,由执行器启动服务器进程。请先在环境中安装服务器及其依赖项。

要运行 Python 版客户查询示例,请安装 MCP SDK。

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

将 Python 服务器脚本保存为 /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。

以下配置会启动 Python 服务器。

{
  "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 套餐。

对于 OpenAI 托管的 stdio MCP 服务器,请省略网络策略或将其设为 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 传输配置可以包含持有者令牌和另一个请求头。

{
  "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 工具。