OpenAI MCP 连接

MCP服务器公开工具定义并执行调用。Agents API发现工具、调用服务器并向智能体返回结果，应用无需逐次处理。

按服务器可达位置选择连接：

从 OpenAI 连接

将HTTP MCP服务器加入 agent.tools，服务器必须对OpenAI可达，有无执行环境均可。例如官方文档MCP支持匿名访问：

来源示例 1（json）：

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}

查看竖版图片

从执行环境连接

执行器MCP从会话环境发起，适合私有网络服务器或环境中已安装软件。

环境类型用 self_hosted 或 openai_hosted。自托管环境在使用工具前连接执行器。

通过 HTTP 连接

服务器已运行时使用HTTP，将以下条目加入 agent.tools，URL改为执行环境可达地址：

来源示例 2（json）：

{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

这里localhost指执行环境。省略 connection_origin 时，连接改由OpenAI发起。

通过 stdio 启动服务器

stdio让执行器启动服务器进程。先在环境安装服务器及依赖。客户查询示例先装MCP SDK：

来源示例 3（bash）：

## [中文] 示例 3：通过 stdio 启动服务器。
## [中文] 按本段命令安装依赖或运行前面的示例文件；仅安装依赖不会创建或完成智能体任务。
python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

服务器保存为 /workspace/lookup_mcp.py：

来源示例 4（python）：

## [中文] 示例 4：通过 stdio 启动服务器。
## [中文] 定义 get_customer MCP 工具并启动所选传输；stdio 由执行器启动进程，HTTP 服务则需预先运行。
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 参数选择脚本传输：

来源示例 5（json）：

{
  "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
}

必须提供 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凭证：存入凭证库，通过 vault_ids 附加。凭证库认证只适用于OpenAI服务发起连接；按服务器URL匹配，多条匹配时用 credential_id 指定。
• stdio凭证：把值放入执行环境，以 transport.env_vars 列出需传给进程的变量名。环境代码可读取值。自托管会话不接受 transport.env 内联值。

例如HTTP传输包含Bearer令牌及另一个请求头：

来源示例 6（json）：

{
  "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 表示初始化失败就让轮次失败；默认初始化不是必需。

全部字段见创建会话参考。

连接排障

必需服务器无法初始化时，检查 agent.session.turn.failed 错误；stdio还需看进程日志。

• 网络：检查URL和 connection_origin；环境连接还需执行器在线且可达服务器。
• 凭证：检查令牌、请求头及凭证库的URL匹配。
• 可执行程序与依赖：命令须能在执行环境运行。
• 工作目录：内联stdio使用存在的绝对 cwd。

相关指南

• 插件：打包MCP配置与技能，跨会话复用。
• 工具搜索：支持模型及提供商的自动MCP发现。