如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

MCP 服务器

将模型连接到远程 MCP 服务器,或通过安全 MCP 隧道连接到本地服务器。

除了通过函数调用向模型提供工具,您还可以使用 远程 MCP 服务器 或 安全 MCP 隧道 扩展模型的能力。模型在响应用户提示词时,可以根据需要使用这些工具连接并控制外部服务。作为开发者,您可以自动允许这些工具调用,也可以要求每次调用先获得您的明确批准。

  • 远程 MCP 服务器可以是公共互联网上的任何服务器,只要它实现了模型上下文协议(MCP)的远程服务器功能。

  • 安全 MCP 隧道可连接本地或私有 MCP 服务器,无需将服务器暴露在公共互联网上。

本指南介绍如何在 Responses API 中使用 MCP 工具。现有模型仍支持内置连接器。有关弃用策略和兼容性示例,请参阅旧版连接器。如果您使用 Agents API 会话,请参阅 MCP 连接,了解如何从托管服务或您的沙盒建立连接。

安全 MCP 隧道

如果您的 MCP 服务器是私有服务器、部署在本地或位于防火墙后方,可以通过安全 MCP 隧道将其连接到支持此功能的 OpenAI 产品,无需将服务器暴露在公共互联网上。请从 openai/tunnel-client 下载最新公开版本。

快速入门

使用 mcp 工具类型即可在 Responses API 中连接 MCP 服务器。要连接远程 MCP 服务器,请设置 server_url。要连接本地 MCP 服务器,请使用 tunnel_id 通过安全 MCP 隧道建立连接。根据服务器的要求,您可能还需要在 authorization 参数中提供 OAuth 访问令牌。

以下示例使用公开的 OpenAI 文档 MCP 服务器查找有关 Responses API 流式输出的文档。此服务器提供只读文档工具,无需身份验证。示例在查询公开文档时跳过了工具调用审批。共享敏感数据时,请启用审批。

在 Responses API 中使用远程 MCP 服务器
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-6.2-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "openai_docs",
        "server_description": "Search and read the public OpenAI documentation.",
        "server_url": "https://developers.openai.com/mcp",
        "require_approval": "never"
      }
    ],
    "input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
  }'

在 Responses API 中,请仅使用您信任的远程 MCP 服务器。恶意服务器可能从进入模型上下文的任何内容中窃取敏感数据。使用此工具前,请仔细阅读下文的风险与安全一节。

API 会在模型响应的 output 数组中返回新的输出项。如果模型决定使用 MCP 服务器,它会先向服务器请求可用工具列表,从而生成一个 mcp_list_tools 输出项。以下输出示例仅列出搜索工具,并缩短了工具描述。该服务器还提供其他文档工具。

{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "openai_docs",
  "tools": [
    {
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      },
      "description": "Search the public OpenAI documentation.",
      "input_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "cursor": {
            "type": "string"
          }
        },
        "required": ["query"]
      },
      "name": "search_openai_docs"
    }
  ]
}

如果模型决定调用 MCP 服务器提供的某个工具,响应中还会包含一个 mcp_call 输出项,显示模型向 MCP 工具发送了什么,以及工具返回了什么。

{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
  "error": null,
  "name": "search_openai_docs",
  "output": "{\"hits\":[{\"url\":\"https://developers.openai.com/api/docs/guides/streaming-responses\"}]}",
  "server_label": "openai_docs"
}

继续阅读,了解 MCP 工具的工作原理、如何筛选可用工具,以及如何处理工具调用审批请求。

工作原理

大多数近期推出的模型都支持在 Responses API 中使用 MCP 工具。您可以在模型文档中查看您的模型是否支持 MCP 工具。使用 MCP 工具时,您只需为导入工具定义或调用工具时消耗的 Token 付费。每次工具调用均不另行收费。

API 调用 MCP 工具的过程分为以下步骤。

第 1 步:列出可用工具

当您在 tools 参数中指定远程 MCP 服务器时,API 会尝试从服务器获取工具列表。Responses API 可连接支持 Streamable HTTP 或 HTTP/SSE 传输协议的远程 MCP 服务器。

成功获取工具列表后,模型响应中会出现一个新的 mcp_list_tools 输出项。该对象的 tools 属性列出已成功导入的工具。以下示例片段仅列出搜索工具,并缩短了工具描述。

{
  "id": "mcpl_68a6102a4968819c8177b05584dd627b0679e572a900e618",
  "type": "mcp_list_tools",
  "server_label": "openai_docs",
  "tools": [
    {
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false
      },
      "description": "Search the public OpenAI documentation.",
      "input_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "cursor": {
            "type": "string"
          }
        },
        "required": ["query"]
      },
      "name": "search_openai_docs"
    }
  ]
}

只要 API 请求的上下文中包含 mcp_list_tools 项,API 就不会在每轮对话中重新向 MCP 服务器获取工具列表。建议您在每次对话或工作流执行期间,都将该项保留在模型上下文中,以减少延迟。

筛选工具

有些 MCP 服务器提供数十个工具。向模型提供大量工具可能会增加费用和延迟。如果您只需要服务器提供的部分工具,可以使用 allowed_tools 参数仅导入这些工具。以下示例只导入 search_openai_docs,用于查找文档链接。

限制允许使用的工具
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6.2-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "openai_docs",
        "server_description": "Search and read the public OpenAI documentation.",
        "server_url": "https://developers.openai.com/mcp",
        "require_approval": "never",
        "allowed_tools": ["search_openai_docs"]
      }
    ],
    "input": "Search the OpenAI docs for Responses API streaming and return the relevant links."
  }'

第 2 步:调用工具

模型获得这些工具的定义后,可以根据上下文决定是否调用工具。当模型决定调用某个 MCP 工具时,API 会向远程 MCP 服务器发出调用请求,将工具输出放入模型上下文,并生成一个 mcp_call 项。为简洁起见,以下输出示例省略了搜索结果的元数据:

{
  "id": "mcp_68a6102d8948819c9b1490d36d5ffa4a0679e572a900e618",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
  "error": null,
  "name": "search_openai_docs",
  "output": "{\"hits\":[{\"url\":\"https://developers.openai.com/api/docs/guides/streaming-responses\"}]}",
  "server_label": "openai_docs"
}

该项包含模型为本次工具调用选择的参数,以及远程 MCP 服务器返回的 output。所有模型都可以选择多次调用 MCP 工具,因此一次 API 请求可能生成多个这样的输出项。

如果工具调用失败,该项的 error 字段会包含 MCP 协议错误、MCP 工具执行错误或一般连接错误。有关 MCP 错误的说明,请参阅 MCP 规范中的错误处理。

审批

默认情况下,在与连接器或远程 MCP 服务器共享任何数据之前,OpenAI 都会请求您审批。通过审批,您可以查看并控制向 MCP 服务器发送的数据。强烈建议您仔细检查与远程 MCP 服务器共享的所有数据,也可以将其记录到日志中。要试用审批流程,请在快速入门示例中将 require_approval 设为 "always",而非 "never",然后运行示例。当 API 就某次 MCP 工具调用请求审批时,Response 对象的输出中会出现一个 mcp_approval_request 项。示例如下:

{
  "id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa",
  "type": "mcp_approval_request",
  "arguments": "{\"query\":\"Responses API streaming\",\"limit\":1}",
  "name": "search_openai_docs",
  "server_label": "openai_docs"
}

批准调用前,请检查请求调用的工具及其参数。随后,您可以创建一个新的 Response 对象并向其中追加一个 mcp_approval_response 项,以回复审批请求。请将以下示例中的响应 ID 和审批请求 ID 替换为您的请求实际返回的 ID。.NET 示例会从初始响应中获取这些 ID。每次审批仅适用于一次工具调用。后续审批请求也请按相同方式处理。

批准 API 请求中的工具调用
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6.2-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "openai_docs",
        "server_description": "Search and read the public OpenAI documentation.",
        "server_url": "https://developers.openai.com/mcp",
        "require_approval": "always"
      }
    ],
    "previous_response_id": "resp_682d498bdefc81918b4a6aa477bfafd904ad1e533afccbfa",
    "input": [{
      "type": "mcp_approval_response",
      "approve": true,
      "approval_request_id": "mcpr_682d498e3bd4819196a0ce1664f8e77b04ad1e533afccbfa"
    }]
  }'

此处使用 previous_response_id 参数,将新的 Response 对象与之前生成审批请求的 Response 对象关联起来。您也可以将一个响应的输出作为下一次请求的输入,从而最大程度地控制哪些内容进入模型上下文。

当您确信某个远程 MCP 服务器值得信任时,可以选择跳过审批以减少延迟。如下例所示,您可以将 MCP 工具的 require_approval 参数设置为一个对象,仅列出您希望跳过审批的工具。也可以将该参数设置为 'never',跳过对该远程 MCP 服务器上所有工具的审批。

对指定工具始终跳过审批
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6.2-astra",
    "tools": [
      {
        "type": "mcp",
        "server_label": "deepwiki",
        "server_url": "https://mcp.deepwiki.com/mcp",
        "require_approval": {
          "never": {
            "tool_names": ["ask_question", "read_wiki_structure"]
          }
        }
      }
    ],
    "input": "What transport protocols does the 2025-03-26 version of the MCP spec (modelcontextprotocol/modelcontextprotocol) support?"
  }'

身份验证

OpenAI 文档 MCP 服务器无需身份验证。其他 MCP 服务器可能要求进行身份验证,最常见的方式是使用 OAuth 访问令牌。请在 MCP 工具的 authorization 字段中提供该令牌:

使用 Stripe MCP 工具
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-6.2-astra",
    "input": "Create a payment link for $20",
    "tools": [
      {
        "type": "mcp",
        "server_label": "stripe",
        "server_url": "https://mcp.stripe.com",
        "authorization": "$STRIPE_OAUTH_ACCESS_TOKEN"
      }
    ]
  }'

为防止敏感令牌泄露,Responses API 不会存储您在 authorization 字段中提供的值。创建的 Response 对象中也不会显示该值。因此,每次向 Responses API 发送创建响应的请求时,都必须提供 authorization 的值。

旧版连接器

对于 2026 年 9 月 1 日之后发布的模型,connector_id 已弃用。请使用 server_url 连接远程 MCP 服务器,或使用 tunnel_id 通过 安全 MCP 隧道连接本地 MCP 服务器。现有模型仍支持连接器。本节示例使用的 gpt-5.2 发布于上述日期之前。

Responses API 内置了少量用于访问第三方服务的连接器。通过这些连接器,您可以从 Dropbox、Gmail 等常用应用中获取上下文,让模型与这些服务交互。

连接器的使用方式与远程 MCP 服务器相同。两者都能让 OpenAI 模型在 API 请求中访问额外的第三方工具。调用远程 MCP 服务器时,您需要传入 server_url。使用连接器时,则需传入 connector_id,它是 API 中可用连接器的唯一标识。

连接器需要 OAuth 访问令牌,由您的应用通过 authorization 参数提供。

在 GPT-5.2 中使用旧版连接器
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
    "model": "gpt-5.2",
    "tools": [
      {
        "type": "mcp",
        "server_label": "Dropbox",
        "connector_id": "connector_dropbox",
        "authorization": "<oauth access token>",
        "require_approval": "never"
      }
    ],
    "input": "Summarize the Q2 earnings report."
  }'

可用连接器

  • Dropbox:connector_dropbox
  • Gmail:connector_gmail
  • Google 日历:connector_googlecalendar
  • Google 云端硬盘:connector_googledrive
  • Microsoft Teams:connector_microsoftteams
  • Outlook 日历:connector_outlookcalendar
  • Outlook 邮件:connector_outlookemail
  • SharePoint:connector_sharepoint

我们优先为没有官方远程 MCP 服务器的服务提供连接器。例如,GitHub 已有官方 MCP 服务器。将 https://api.githubcopilot.com/mcp/ 传入 MCP 工具的 server_url 字段即可连接。

为连接器授权

请在 authorization 字段中传入 OAuth 访问令牌。您的应用必须单独处理 OAuth 客户端注册和授权。

测试时,您可以使用 Google 的 OAuth 2.0 Playground 生成临时访问令牌,并在 API 请求中使用。

要在 Playground 中测试 API 的连接器功能,请先输入以下内容:

https://www.googleapis.com/auth/calendar.events

请在第 1 步:选择 API 并授权中输入上述授权范围,以允许 API 读取 Google 日历中的活动。

使用您的 Google 账号为应用授权后,您会进入第 2 步:用授权码换取令牌。这一步会生成访问令牌,供您在使用 Google 日历连接器的 API 请求中使用:

使用 Google 日历连接器
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.2",
    "tools": [
      {
        "type": "mcp",
        "server_label": "google_calendar",
        "connector_id": "connector_googlecalendar",
        "authorization": "ya29.A0AS3H6...",
        "require_approval": "never"
      }
    ],
    "input": "What is on my Google Calendar for today?"
  }'

通过连接器调用 MCP 工具与通过远程 MCP 服务器调用 MCP 工具的输出格式相同,输出项的类型都是 mcp_call。在此示例中,传给连接器的参数和连接器返回的响应都是 JSON 字符串:

{
  "id": "mcp_68a62ae1c93c81a2b98c29340aa3ed8800e9b63986850588",
  "type": "mcp_call",
  "approval_request_id": null,
  "arguments": "{\"time_min\":\"2025-08-20T00:00:00\",\"time_max\":\"2025-08-21T00:00:00\",\"timezone_str\":null,\"max_results\":50,\"query\":null,\"calendar_id\":null,\"next_page_token\":null}",
  "error": null,
  "name": "search_events",
  "output": "{\"events\": [{\"id\": \"2n8ni54ani58pc3ii6soelupcs_20250820\", \"summary\": \"Home\", \"location\": null, \"start\": \"2025-08-20T00:00:00\", \"end\": \"2025-08-21T00:00:00\", \"url\": \"https://www.google.com/calendar/event?eid=Mm44bmk1NGFuaTU4cGMzaWk2c29lbHVwY3NfMjAyNTA4MjAga3doaW5uZXJ5QG9wZW5haS5jb20&ctz=America/Los_Angeles\", \"description\": \"\\n\\n\", \"transparency\": \"transparent\", \"display_url\": \"https://www.google.com/calendar/event?eid=Mm44bmk1NGFuaTU4cGMzaWk2c29lbHVwY3NfMjAyNTA4MjAga3doaW5uZXJ5QG9wZW5haS5jb20&ctz=America/Los_Angeles\", \"display_title\": \"Home\"}], \"next_page_token\": null}",
  "server_label": "Google_Calendar"
}

各连接器提供的工具

可用工具取决于您的 OAuth 令牌具有哪些授权范围。展开下表,即可查看连接到各个应用时可以使用的工具。

延迟加载 MCP 服务器中的工具

如果您使用工具搜索,可以等到模型确定需要某个函数时,再加载 MCP 服务器提供的该函数。要启用此功能,请在 MCP 服务器的工具定义中设置 defer_loading: true。

启用延迟加载后,模型仍可根据 MCP 服务器的标签和描述决定何时搜索该服务器上的工具,但只有在需要时才会加载具体的函数定义。这有助于减少总体 Token 用量,尤其适合提供大量函数的 MCP 服务器。

{
    "type": "mcp",
    "server_label": "openai_docs",
    "server_description": "Search and read the public OpenAI documentation.",
    "server_url": "https://developers.openai.com/mcp",
    "defer_loading": true,
    "require_approval": "never"
}

风险与安全

MCP 工具可以将 OpenAI 模型连接到外部服务。这项功能很强大,但也伴随一些风险。

使用连接器可能会将敏感数据发送给 OpenAI,或允许模型读取相关服务中可能含有敏感信息的数据。

远程 MCP 服务器也存在这些风险,而且 OpenAI 未对这些服务器进行验证。这些服务器可以让模型访问、发送和接收数据,以及在相关服务中执行操作。所有 MCP 服务器均属于第三方服务,适用各自的条款和条件。

如果您发现恶意 MCP 服务器,请向 security@openai.com 举报。

集成连接器和远程 MCP 服务器时,请参考以下最佳实践。

提示词注入

在任何 LLM 应用中,提示词注入都是需要重视的安全问题。如果模型可以使用能够访问敏感数据或执行操作的 MCP 服务器和连接器,这一点尤为重要。如果模型的提示词包含用户提供的内容,请谨慎使用这些工具,并采取适当的防护措施。

例如,网页中的指令可能会让模型在您的 CRM 系统中查找某位客户,并将该客户的电子邮件地址放入 URL 中。即使 CRM 工具只有只读权限,访问该 URL 也会泄露客户的电子邮件地址。

要将一家公司的公开公告与私有 CRM 记录进行比对,请在第一个请求中仅启用网页搜索,收集公开信息。然后,将其中与比对有关的信息传入第二个请求,并仅允许该请求使用您的内部 CRM 搜索工具。这样,客户记录就不会出现在网页搜索的查询内容或 URL 中。

敏感操作必须经过审批

请配置 require_approval 和 allowed_tools 参数,确保所有敏感操作都必须经过审批流程。

MCP 工具调用和输出中的 URL

连接器或远程 MCP 服务器的工具调用输出可能包含 URL。向这些 URL 发送请求,或在应用中嵌入工具返回的图片 URL,都可能带来风险。在应用代码中嵌入这些 URL 或以其他方式使用它们之前,请确认提供这些 URL 的域名和服务值得信任。

连接到可信服务器

请选择由服务提供商自行托管的官方服务器。例如,我们建议连接 Stripe 在 mcp.stripe.com 托管的官方服务器,而非第三方托管的 Stripe MCP 服务器。目前官方远程 MCP 服务器数量有限,您可能会考虑使用其他组织托管的 MCP 服务器。这些组织并不运营目标服务,而是通过您的 API 将请求转发给该服务。如果必须采用这种方式,请格外谨慎地调查这些“聚合服务商”,并仔细审查它们如何使用您的数据。

记录并审查与第三方 MCP 服务器共享的数据

MCP 服务器自行定义其工具,因此工具可能会请求一些您不愿与服务器运营方共享的数据。为此,Responses API 中的 MCP 工具默认要求每次 MCP 工具调用都经过审批。开发应用时,请全面、仔细地检查与这些服务器共享的数据类型。当您确信某个 MCP 服务器值得信任后,可以跳过审批以减少执行延迟。

我们也建议记录发送到 MCP 服务器的所有数据。如果您在使用 Responses API 时设置了 store=true,API 会将这些数据记录并保留 30 天,除非您的组织已启用零数据保留。您也可以在自己的系统中记录这些数据,并定期审查,确认实际共享的数据符合您的预期。

恶意 MCP 服务器可能包含隐藏指令(提示词注入),试图诱使 OpenAI 模型执行非预期操作。OpenAI 已内置防护机制,帮助检测和阻止这些威胁,但您仍须仔细审查输入和输出,并确保只与可信服务器建立连接。

MCP 服务器可能会在您不知情的情况下更改工具的行为,从而导致非预期行为或恶意行为。

对零数据保留和数据驻留的影响

MCP 工具与零数据保留和数据驻留兼容。请注意,MCP 服务器属于第三方服务,发送到 MCP 服务器的数据受相应服务的数据保留和数据驻留政策约束。

例如,如果您的组织选择了欧洲数据驻留,在向 MCP 服务器发送消息或数据之前,OpenAI 仅在欧洲对客户内容执行推理和存储。您有责任确保 MCP 服务器也符合适用于您的所有零数据保留或数据驻留要求。有关零数据保留和数据驻留的更多信息,请参阅数据指南。

使用说明

API 支持情况速率限制备注

构建
1000 RPM

发布和增长
2000 RPM

定价
零数据保留与数据驻留