如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

身份验证

插件 MCP 服务器的身份验证方式。

验证用户身份

许多插件 MCP 服务器可以在只读模式下接受匿名访问,但只要涉及特定客户的数据或写入操作,就应验证用户身份。

已发布的插件可以在 ChatGPT 和 Codex 中运行。MCP 授权约定适用于这两款产品。当两款产品使用的回调、元数据文档或账号关联界面有所区别时,本指南会说明 ChatGPT 客户端的具体行为。

如果您需要连接现有的服务端应用或在用户之间共享数据,可以集成自己的授权服务器。

使用 OAuth 2.1 自定义身份验证

对于需要身份验证的 MCP 服务器,您应实现符合 MCP 授权规范的 OAuth 2.1 流程。

组成部分

  • 资源服务器: 您的 MCP 服务器,负责提供工具并验证每个请求的访问令牌。
  • 授权服务器: 您的身份提供方或自行实现的服务,负责签发令牌并发布发现元数据。
  • 客户端: 代表用户执行操作的 OpenAI 主机,例如 ChatGPT 或 Codex。受支持的客户端可使用客户端 ID 元数据文档(CIMD)、动态客户端注册(DCR)、预定义的 OAuth 客户端以及 PKCE。

MCP 授权规范的要求

  • 在 MCP 服务器上托管受保护资源元数据
  • 在授权服务器上发布 OAuth 元数据
  • 在整个 OAuth 流程中原样传递 resource 参数
  • 选择 OpenAI 主机标识或注册其 OAuth 客户端的方式:CIMD、DCR 或预定义的 OAuth 客户端
  • 发布授权服务器的令牌端点接受的身份验证方法

下面逐项说明这些要求。

在 MCP 服务器上托管受保护资源元数据

  • 您需要提供 HTTPS 端点,例如 GET https://your-mcp.example.com/.well-known/oauth-protected-resource,也可以通过 WWW-Authenticate 响应头在 401 Unauthorized 响应中公布同一 URL,以便 ChatGPT 知道从哪里获取元数据。
  • 该端点返回一个 JSON 文档,描述资源服务器及其可用的授权服务器:
{
  "resource": "https://your-mcp.example.com",
  "authorization_servers": ["https://auth.yourcompany.com"],
  "scopes_supported": ["files:read", "files:write"],
  "resource_documentation": "https://yourcompany.com/docs/mcp"
}
  • 请填写以下关键字段,其中标为可选的字段可按需提供:
    • resource:MCP 服务器的规范 HTTPS 标识符。在 OAuth 流程中,ChatGPT 会将该值原样作为 resource 查询参数发送。
    • authorization_servers:一个或多个指向身份提供方的签发者基础 URL。ChatGPT 会逐一尝试,从中查找 OAuth 元数据。
    • scopes_supported:可选的授权范围列表,帮助 ChatGPT 向用户说明即将请求哪些权限。
    • RFC 9728 中的可选字段(例如 resource_documentation、resource_policy_uri 或 resource_tos_uri)有助于客户端和管理员了解您的配置。

如果因请求未经身份验证而拒绝该请求,请返回类似以下内容的身份验证质询:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

仅凭这个响应头,ChatGPT 就能发现此前未知的元数据 URL。

在授权服务器上发布 OAuth 元数据

  • 身份提供方必须在标准位置提供以下发现文档之一,以便 ChatGPT 读取其配置:
    • OAuth 2.0 元数据:https://auth.yourcompany.com/.well-known/oauth-authorization-server
    • OpenID Connect 元数据:https://auth.yourcompany.com/.well-known/openid-configuration
  • 每种文档都向 OpenAI 主机说明三件事:将用户重定向到哪里、如何用授权码换取令牌,以及如何表明自身的客户端身份。典型响应如下:
{
  "issuer": "https://auth.yourcompany.com",
  "authorization_response_iss_parameter_supported": true,
  "authorization_endpoint": "https://auth.yourcompany.com/oauth2/v1/authorize",
  "token_endpoint": "https://auth.yourcompany.com/oauth2/v1/token",
  "client_id_metadata_document_supported": true,
  "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
  "registration_endpoint": "https://auth.yourcompany.com/oauth2/v1/register",
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["files:read", "files:write"]
}
  • 以下字段必须正确配置:
    • issuer:授权服务器的规范标识符。请在受保护资源元数据的 authorization_servers 列表中使用完全相同的值。
    • authorization_response_iss_parameter_supported:只有当授权服务器在每个授权响应(包括错误响应)中都返回 iss 参数时,才将此字段设为 true。
    • authorization_endpoint、token_endpoint:ChatGPT 执行完整的 OAuth 授权码 + PKCE 流程所需的 URL。
    • client_id_metadata_document_supported:如果您希望 ChatGPT 使用 CIMD 注册客户端,请将此字段设为 true。ChatGPT 优先使用 CIMD,但如果 CIMD 和 DCR 均可用,插件开发者也可以选择 DCR。
    • token_endpoint_auth_methods_supported:列出授权服务器的令牌端点接受的身份验证方法。这项要求适用于 CIMD、DCR 和预定义的 OAuth 客户端。使用 CIMD 时,ChatGPT 支持通过 none 让公共客户端换取令牌,也支持通过 private_key_jwt 使用已签名的客户端断言换取令牌。其他 OAuth 客户端通常使用 none、client_secret_post 或 client_secret_basic。
    • registration_endpoint:如果您支持动态客户端注册(DCR),请提供此字段。这样,ChatGPT 就能为 MCP 服务器连接创建并重复使用专用的 client_id。
    • code_challenge_methods_supported:必须包含 S256。如果授权服务器元数据省略该字段,或未声明支持 S256,则相应的 MCP 服务器不受支持。这是 MCP 授权规范的要求。
    • 可选字段遵循 RFC 8414 和 OpenID 发现规范。您可以添加有助于管理员配置策略的字段。

OIDC 授权范围

  • 如果身份提供方声明了 OIDC 授权范围(例如 openid、email、profile),并在 .well-known/oauth-authorization-server 或 .well-known/openid-configuration 文档的 scopes_supported 字段中列出这些范围,ChatGPT 会在 OAuth 流程中默认请求这些范围。
  • 某些身份提供方可能不会默认启用其声明的 OIDC 授权范围。无论 OAuth 客户端使用 CIMD、由您手动创建还是通过 DCR 创建,都请检查身份提供方的配置,确保为该客户端启用了所有已声明的范围。

支持工作空间域名限制

ChatGPT Enterprise 工作空间可以验证电子邮件域名的所有权。当通过 OAuth 关联的插件提供用户已验证的电子邮件地址时,ChatGPT 可以根据邮箱域名,阻止用户在个人工作空间或组织外的其他工作空间中使用该企业身份关联插件。

要支持这项保护措施,请将授权服务器配置为:

  • 发布 OpenID Connect 发现元数据。
  • 声明并启用 openid 和 email 授权范围。
  • 公布 UserInfo 端点,并通过该端点返回用户的 email 声明和 email_verified: true。

您也可以在 OAuth 流程中通过 ID 令牌返回这些声明,但实施工作空间域名限制必须提供 UserInfo 端点。

Enterprise 工作空间也必须验证自己的域名。授权服务器负责提供用户身份,ChatGPT 会将其与工作空间配置的已验证域名进行比对。授权服务器不负责验证工作空间是否拥有该域名。

在重新授权时保留登录上下文

当 ChatGPT 为现有连接重新授权时(包括请求额外的 OAuth 授权范围),它可能会通过标准的 id_token_hint 参数,在授权请求中附上之前的 OIDC ID 令牌。要让用户无需从头登录就能授予额外权限,请将授权服务器配置为在首次 OAuth 流程中签发 ID 令牌,并在授权时使用 id_token_hint。

这项优化是可选的。如果没有可用的 ID 令牌,或者授权服务器不使用该提示,重新授权仍可正常进行。

通过签发者标识保护回调

OpenAI 主机使用 RFC 9207 签发者标识机制保护 OAuth 回调,防范授权服务器混淆攻击。要让 ChatGPT 和 Codex 在创建符合条件的 OAuth 客户端时使用固定的重定向 URI,请执行以下操作:

  • 将 authorization_response_iss_parameter_supported: true 写入授权服务器元数据。
  • 在元数据的 issuer 字段和受保护资源元数据的 authorization_servers 列表中使用完全相同的签发者标识符。
  • 在每个授权响应(包括成功响应和错误响应)中返回 iss。其值必须与元数据中的 issuer 完全一致。客户端会逐字比较字符串,不会对末尾斜杠、路径、端口或大小写进行规范化处理。

ChatGPT 和 Codex 在重定向用户之前,会记录所选授权服务器元数据中的 issuer,并在用授权码换取令牌之前检查返回的 iss。如果服务器声明支持签发者标识,却未返回 iss 或返回了不匹配的值,ChatGPT 和 Codex 会拒绝该响应。这些要求遵循 MCP 授权响应验证规则。

重定向 URL

将 MCP 服务器管理页面显示的生产环境重定向 URI 原样复制到授权服务器的允许列表中。

  • 如果授权服务器不满足上述签发者标识要求,ChatGPT 会使用与回调 ID 对应的重定向 URI https://chatgpt.com/connector/oauth/{callback_id}。
  • 如果授权服务器满足这些要求,ChatGPT 会使用固定的重定向 URI https://chatgpt.com/connector_platform_oauth_redirect。

在 ChatGPT 引入按回调 ID 区分的重定向机制之前发布的 MCP 服务器,也会继续使用固定的重定向 URI。

在整个 OAuth 流程中原样传递 resource 参数

  • ChatGPT 会在授权请求和令牌请求中都附加 resource=https%3A%2F%2Fyour-mcp.example.com。这会将令牌与上文所示的受保护资源元数据关联起来。
  • 请将授权服务器配置为把该值复制到访问令牌中(通常写入 aud 声明),以便 MCP 服务器验证该令牌是否专为自身签发。
  • 如果收到的令牌缺少预期的受众或授权范围,请拒绝该令牌,并通过 WWW-Authenticate 质询提示 ChatGPT 使用正确的参数重新授权。

支持授权码流程

  • ChatGPT 作为 MCP 客户端,使用 PKCE 和 S256 码质询执行授权码流程,防止攻击者重放截获的授权码。
  • 授权服务器必须发布 code_challenge_methods_supported 字段并在其中列出 S256,以便客户端通过元数据确认服务器支持 PKCE。

OAuth 流程

实现上述 MCP 授权规范后,OAuth 流程如下:

  1. ChatGPT 向 MCP 服务器查询受保护资源元数据。

  1. ChatGPT 表明自己的 OAuth 客户端身份。如果 MCP 服务器使用 CIMD,ChatGPT 会跳过动态客户端注册,并将 CIMD 文档 URL 作为 client_id 发送。对于满足上述签发者标识要求的授权服务器,ChatGPT 使用固定的 https://chatgpt.com/oauth/client.json。对于其他服务器,则使用与回调 ID 对应的 https://chatgpt.com/oauth/{callback_id}/client.json。MCP 服务器管理页面会显示该连接的回调模式所用的确切客户端元数据文档和重定向 URI。如果 MCP 服务器使用 DCR,ChatGPT 会针对该 MCP 服务器连接调用一次授权服务器的 registration_endpoint,接收生成的 client_id,之后为该连接重复使用同一客户端。

使用 CIMD 时无需执行客户端注册。下图展示的是 DCR 流程:

  1. 当用户首次调用工具时,ChatGPT 客户端会启动 OAuth 授权码 + PKCE 流程。用户完成身份验证,并同意授予所请求范围内的权限。

  1. ChatGPT 使用授权码换取访问令牌,并将其附加到后续的 MCP 请求中(Authorization: Bearer <token>)。

  1. 服务器在执行工具之前,验证每个请求的令牌,包括签发者、受众、到期时间和授权范围。

客户端注册

如果授权服务器支持客户端 ID 元数据文档(CIMD),且插件开发者选择了该方式,请优先使用它注册客户端。使用 CIMD 时,ChatGPT 将 HTTPS 元数据文档 URL 用作 client_id。授权服务器获取该文档,验证其中公布的客户端元数据和重定向资源标识符,并将该 URL 作为 ChatGPT 的固定客户端标识。

如果您支持 CIMD,请在授权服务器元数据中设置 client_id_metadata_document_supported: true。这样,ChatGPT 就能针对选择 CIMD 的 MCP 服务器使用同一个固定的客户端标识,授权服务器也可以基于该标识配置重定向 URI 允许列表、速率限制和其他策略。

ChatGPT 正在采用 MCP SEP-3149 提出的 CIMD 过渡方案。其生产环境 CIMD 文档以数组形式发布 token_endpoint_auth_methods_supported,列出 ChatGPT 可以使用的方法,不区分优先级。在过渡期间,文档还会发布旧版单数字段 token_endpoint_auth_method,用于指明首选方法:

{
  "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
  "token_endpoint_auth_method": "private_key_jwt"
}

复数字段在两份文档中分别表示不同一方支持的方法:授权服务器元数据列出令牌端点接受的方法,ChatGPT 的 CIMD 文档列出 ChatGPT 可以使用的方法。ChatGPT 从两者的交集中选择一种方法。如果交集包含旧版单数字段指定的首选方法,ChatGPT 会使用该方法,以兼容仍将单数字段视为强制要求的授权服务器。否则,ChatGPT 可以使用交集中的其他方法。

读取 CIMD 复数字段的授权服务器应接受交集中的任何方法,除非本地安全策略禁止该客户端使用其中某种方法。授权服务器必须拒绝交集以外的方法。client_id URL 保持固定,不会通过查询参数选择特定方法对应的文档。

支持以下方法:

  • none:如果令牌端点支持基于 PKCE 的授权码交换,且无需验证客户端身份,请使用此公共客户端流程。ChatGPT 不会为各客户端存储专用密钥。
  • private_key_jwt:如果令牌端点要求验证客户端身份,请使用此签名客户端断言流程。ChatGPT 会在 CIMD 元数据中公布一个公共 JWKS URL。JWKS 位于元数据同源地址下的 /oauth/jwks.json。ChatGPT 在服务端使用托管私钥签署令牌请求,并通过 kid 标识密钥。授权服务器使用公共 JWKS 验证断言。

ChatGPT 仍然支持 DCR。如果您提供 registration_endpoint,当插件开发者选择 DCR 或 CIMD 不可用时,ChatGPT 可以动态注册。ChatGPT 为每个 MCP 服务器连接执行一次 DCR,然后保存已注册的 OAuth 客户端,并为该连接重复使用它。大量独立连接仍可能通过 DCR 注册大量客户端,因此规模较大时,使用 CIMD 通常更易于管理。

只要 MCP 服务器连接仍在使用,就应确保已注册的 OAuth 客户端及其客户端密钥(如有)保持有效。如果授权服务器使其中任一凭据过期、将其删除或替换,用户和审核人员在连接时可能会收到 invalid_client 错误。访问令牌和刷新令牌仍可正常过期或轮换。

识别客户端身份

一个常见问题是,MCP 服务器如何确认请求确实来自 ChatGPT。ChatGPT 在连接 MCP 服务器时会出示由 OpenAI 管理的客户端证书,因此您可以在传输层通过 mTLS 验证客户端身份。您还可以将 ChatGPT 公布的出站 IP 地址范围加入允许列表。ChatGPT 不支持机器间 OAuth 授权,例如客户端凭据、服务账号或 JWT 持有者断言,也无法出示自定义 API 密钥或客户提供的 mTLS 证书。

CIMD 通过 HTTPS 提供固定的 ChatGPT 身份声明,让授权服务器能更可靠地识别客户端。如果您使用 private_key_jwt,请使用 CIMD 元数据中公布的公共 JWKS 验证 ChatGPT 提交给令牌端点的客户端断言。

双向 TLS(mTLS)

ChatGPT 现在会在与 MCP 服务器建立 TLS 连接时出示由 OpenAI 管理的客户端证书。如果您的应用会验证客户端证书,请将其配置为信任以下 OpenAI 证书链。

在与 MCP 服务器建立 TLS 连接时,请按以下方式验证客户端证书:

  • 确认客户端出示了叶证书,且其证书链可追溯到 OpenAI Connectors mTLS 中间 CA。
  • 确认叶证书可用于客户端身份验证。
  • 确认叶证书的 SAN dnsName 为 mtls.prod.connectors.openai.com。
  • 避免固定叶证书指纹。OpenAI 可能会轮换叶证书,但轮换后的证书仍属于已公布的 CA 证书链。

使用 mTLS 验证 ChatGPT 作为 MCP 客户端的身份。请继续使用 OAuth 2.1 验证最终用户的身份并授予工具访问权限。

选择身份提供方

大多数 OAuth 2.1 身份提供方都能满足 MCP 授权要求,前提是它们提供发现文档,支持通过 none 或 private_key_jwt 使用 CIMD,在需要时支持 DCR,并将 resource 参数原样写入所签发的令牌。请优先选择支持通过 CIMD 注册客户端的提供方。

我们 强烈 建议您使用现有的成熟身份提供方,而不要自行从头实现身份验证。

以下是一些常用身份提供方的相关指南。

Auth0

Auth0 提供元数据发现、CIMD 注册、API 安全保护以及第一方和第三方工具调用所需的令牌交换功能,让 MCP 客户端能够安全地连接 MCP 服务器。

托管身份提供方示例(Stytch)

实现令牌验证

OAuth 流程完成后,ChatGPT 会将收到的访问令牌直接附加到后续的 MCP 请求中(Authorization: Bearer …)。MCP 服务器收到请求时,您必须先将令牌视为不可信,并自行完成资源服务器所需的全部检查,包括验证签名、匹配签发者和受众、检查有效期、考虑重放风险以及强制执行授权范围限制。这些检查由您负责,ChatGPT 不会代为执行。

具体步骤如下:

  • 获取授权服务器公布的签名密钥(通常通过 JWKS 获取),并验证令牌的签名和 iss。
  • 拒绝已过期或尚未生效的令牌(exp/nbf)。
  • 确认令牌是为您的服务器签发的(检查 aud 或 resource 声明),并且包含您标记为必需的授权范围。
  • 执行服务器特有的策略检查,然后将解析出的身份附加到请求上下文中,或返回 401 响应并附上 WWW-Authenticate 质询。

如果验证失败,请返回 401 Unauthorized,并附上指向受保护资源元数据的 WWW-Authenticate 响应头。这会提示客户端重新执行 OAuth 流程。

SDK 的令牌验证基础功能

Python 和 TypeScript 的 MCP 软件开发工具包都提供了辅助功能,因此您无需从头实现令牌验证。

支持多个账号

多账号功能允许用户将多个账号连接到同一个插件,例如个人账号和工作账号。OpenAI 会使用所选连接经过身份验证的凭据来路由每次工具调用。即使没有用户资料工具,用户也能连接多个账号。为了帮助用户区分连接,并让系统在重新连接后识别出同一份用户资料,请提供需要身份验证的用户资料工具,并让它返回稳定的 ID 和有助于区分账号的显示元数据。

用户如何使用多个账号

用户可以在插件设置页面连接更多账号。模型可以使用所有已连接的账号,并在调用工具时根据用户的请求选择一个或多个相关账号。每次工具调用都使用所选账号的凭据和权限。

改进账号识别

为了帮助 OpenAI 识别已连接的用户资料并显示有意义的标签,请执行以下操作:

  • 提供需要身份验证的用户资料工具,让它返回一个不透明 ID,唯一且稳定地标识请求凭据所对应的用户资料。这样,OpenAI 就能在重新连接后识别同一份资料,并将其与其他资料区分开。只有字段值能满足这些要求时,名为 id 的字段才能用于识别资料。
  • 在 MCP 元数据中指定用户资料工具,以便 OpenAI 确定应调用哪个工具来获取经身份验证的用户资料。

需要用户资料时,OpenAI 会在运行时找到指定的工具,使用连接的凭据调用它,并在使用资料数据前验证响应。即使没有用户资料工具,用户仍然可以连接账号,但账号标签可能不够准确,识别账号或检测重复账号也可能不够可靠。如果您声明了用户资料工具,请确保它返回有效的身份信息。无效响应可能导致账号无法连接。

定义稳定的用户资料标识

用户资料用于标识请求中已验证凭据所代表的身份。哪些资料可以独立连接,由您的服务决定。此约定不规定服务的组织结构或授权模型。

请返回一个在应用内唯一的不透明用户资料 ID。同一份资料的 ID 在令牌刷新和重新连接后必须保持不变,不同资料必须使用不同的 ID。OpenAI 只比较这些 ID,不解读其内容。

如果提供方已有不可变的不透明 ID,且它能标识完整的用户资料,请使用该 ID。否则,请为资料一次性分配一个不透明 ID,持久保存二者的对应关系,并在后续请求中取回同一个 ID。请在服务内部维护各种关联关系,不要将姓名、电子邮件地址或组织关系编码到返回的 ID 中。

您的 id 必须满足以下要求:

  • 使用非空且不全为空白字符的字符串。请将提供方的数字 ID 序列化为字符串。
  • 对于同一份资料,在令牌刷新、重新连接和扩大授权范围后保持不变。
  • 对于可以通过应用连接的不同资料,使用不同的 ID。
  • 资料的电子邮件地址、姓名或显示标签变更时,ID 保持不变。
  • 删除资料后,绝不将其 ID 重新分配给其他资料。

不要为每次登录、每个令牌、每个会话或每次工具调用生成新的 ID。请将电子邮件地址和可编辑的姓名放在显示元数据中。可能发生变更或重新分配的电子邮件地址不能用作稳定的用户资料 ID。对于 Google OIDC,请使用稳定的 sub,不要使用电子邮件声明。Google 文档说明,电子邮件地址可能会变更,而 sub 保持不变,且绝不会分配给其他身份。请参阅 Google 身份文档。

更新集成时,请保留现有的用户资料 ID。更改显示名称、签发新令牌或建立新连接都不得产生新的用户资料标识。

实现并声明用户资料工具

提供一个需要身份验证的只读工具,让它接受空的参数对象并返回当前用户资料。该工具可以命名为 get_profile、whoami 或其他名称。工具的元数据会将其标识为用户资料工具,以便在运行时发现它。响应必须满足以下身份要求,OpenAI 才能正确使用它。

  • 根据请求中已验证的凭据确定身份。
  • 确保操作为只读,且使用连接的常规权限即可执行。
  • 仅返回一份资料,即当前请求凭据所代表的用户资料。
  • 不要要求调用方提供用户 ID、电子邮件地址或账号选择器。
  • 身份验证失败时,请返回相应的身份验证错误,不要返回占位 ID 或其他账号的资料。

用户资料响应必须符合以下 JSON 模式:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "Opaque profile identifier, unique within this app and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile."
    },
    "name": {
      "type": "string",
      "description": "Display name for the authenticated profile."
    },
    "email": {
      "type": "string",
      "description": "Email address for display; not used as the profile identity."
    },
    "nickname": {
      "type": "string",
      "description": "A useful label that helps users distinguish connected profiles."
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

响应必须包含字符串 id,其值不能为空或仅由空白字符组成。显示字段是可选的。工具元数据告诉 OpenAI 从哪里获取用户资料,响应则标识当前凭据所代表的资料。

模式验证会检查响应是否具备处理用户资料所需的结构和字段类型。您的服务还必须确保 ID 唯一、稳定,且返回的资料与凭据对应。仅凭元数据或通过模式检查,都无法证明服务满足这些行为要求。

如果有 name、email 或 nickname,请提供其中可用的字段,以便用户区分资料。请省略无法提供的可选值,不要编造,也不要添加无关的个人数据。请将便于用户理解的说明放入 nickname,不要写入 ID。

使用 _meta["openai/profile"]: true 标记该工具,并将用户资料响应模式发布为工具的 outputSchema。这个标记告诉 OpenAI 哪个工具提供用户资料,本身不会启用该功能或赋予使用资格。如果标记缺失或为假,则表示未通过此机制将该工具指定为资料来源。字符串、数字和 null 均为无效的标记值。

{
  "name": "get_profile",
  "description": "Return the profile represented by this request's authenticated credentials. The opaque id is unique within this app and remains unchanged across token refresh, reconnection, and display-metadata changes.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "pattern": "\\S",
        "description": "Opaque profile identifier, unique within this app and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile."
      },
      "name": {
        "type": "string",
        "description": "Display name for the authenticated profile."
      },
      "email": {
        "type": "string",
        "description": "Email address for display; not used as the profile identity."
      },
      "nickname": {
        "type": "string",
        "description": "A useful label that helps users distinguish connected profiles."
      }
    },
    "required": ["id"],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "oauth2",
      "scopes": []
    }
  ],
  "_meta": {
    "openai/profile": true
  }
}

如果访问用户资料需要特定的 OAuth 授权范围,请填写您的集成实际使用的范围。工具声明本身不会执行身份验证,服务器必须验证凭据并强制执行权限检查。请参阅实现令牌验证和工具参考。

请在 structuredContent 中返回用户资料,以便根据 outputSchema 进行验证。为确保兼容性,还应将同一份资料序列化为 JSON,放入一个文本内容项中:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"prf_8d7e4b19\",\"name\":\"Alex Chen\",\"email\":\"alex@example.com\",\"nickname\":\"Alex — Moonwaffle work\"}"
    }
  ],
  "structuredContent": {
    "id": "prf_8d7e4b19",
    "name": "Alex Chen",
    "email": "alex@example.com",
    "nickname": "Alex — Moonwaffle work"
  },
  "isError": false
}

使用单个 JSON 对象,并将用户资料字段放在顶层。

已经有用户资料工具? 请保留工具名称,添加用户资料元数据声明,并返回标准的用户资料响应。如果现有响应结构不同,请在服务器上调整,或提供一个符合模式的轻量封装工具。标准集成方式对所有应用使用相同的声明和响应结构。

具体示例:持久保存 Moonwaffle 用户资料

假设有一个名为 Moonwaffle 的虚构服务,允许 Alex 分别连接两份用户资料。Moonwaffle 为每份资料保存不同的不透明 ID。服务根据请求凭据找到其中一份已保存的资料,用户资料工具则返回该资料已有的 ID。

已保存的用户资料示例。 标签可以更改,标识符保持不变:

Alex — Moonwaffle personal: prf_42a9c6e0
Alex — Moonwaffle work:     prf_8d7e4b19

示例中的 ID 不包含资料标签或内部关联关系。每份资料的 ID 只需保存一次,在重新连接、刷新令牌以及更改电子邮件地址或显示名称后都沿用同一个 ID。

根据通过身份验证的用户资料构建响应。 以下示例展示了可接入 MCP SDK 的处理逻辑。

loadAuthenticatedProfile 是您在应用中实现的集成代码,负责验证请求凭据、执行这些凭据对应的权限检查,并获取相应资料已保存的 ID 和显示元数据。requestContext 由服务器处理请求时提供,不是模型传入的工具参数。

返回通过身份验证的用户资料
async function getProfile(requestContext: { token: string }) {
  // Your auth/provider integration validates credentials and loads
  // the existing profile. Auth failures use normal MCP auth handling.
  const account = await loadAuthenticatedProfile(requestContext);
  const id = account.profileId;

  if (typeof id !== "string" || id.trim().length === 0) {
    return {
      isError: true,
      content: [{ type: "text", text: "Profile identity unavailable." }],
    };
  }

  // Return the persisted ID unchanged; do not generate an ID per call.
  const profile = {
    id,
    ...(typeof account.name === "string" ? { name: account.name } : {}),
    ...(typeof account.email === "string" ? { email: account.email } : {}),
    ...(typeof account.nickname === "string"
      ? { nickname: account.nickname }
      : {}),
  };

  return {
    isError: false,
    structuredContent: profile,
    content: [{ type: "text", text: JSON.stringify(profile) }],
  };
}

使用上面的元数据声明以及输入和输出模式注册该处理函数。查找用户资料时,等效凭据必须指向同一份已保存的资料,重新连接后也必须如此。不得为每次 OAuth 授权或每个会话创建新的资料 ID。其他所有工具都必须根据请求凭据执行同一份资料对应的权限检查。

验证身份标识是否符合预期:

测试 预期结果
多次调用工具获取 Moonwaffle 工作资料 每次均返回 prf_8d7e4b19
刷新令牌、重新连接或扩大授权范围后获取同一份资料 prf_8d7e4b19
更改电子邮件地址或显示标签后获取同一份资料 prf_8d7e4b19,标签可以变更
获取 Moonwaffle 个人资料 prf_42a9c6e0,与工作资料的 ID 不同
已保存的资料 ID 缺失或为空白 返回错误,不编造身份,也不回退到其他资料

所有用户资料都必须满足这些身份标识要求,今后更改集成时也必须保持这一点。无论显示元数据、令牌内容或连接生命周期发生怎样的变化,都要确保身份标识符合要求。

测试与发布

  • 本地测试: 先使用签发短期令牌的开发租户,以便快速迭代。
  • 内部试用: 身份验证可以正常运行后,先仅向可信的测试人员开放,再逐步扩大使用范围。您可以要求用户必须关联账号才能使用特定工具或整个 MCP 服务器。
  • 轮换: 提前规划如何处理令牌撤销、刷新和授权范围变更。如果令牌缺失或已失效,服务器应将请求视为未经身份验证,并返回有助于排查问题的错误消息。
  • OAuth 调试: 发布前,使用 MCP Inspector 的 Auth 设置逐步执行 OAuth 流程,定位出错的环节。

完成身份验证配置后,您就可以向 ChatGPT 和 Codex 用户提供与其身份对应的数据和写入操作。

触发身份验证界面

只有当 MCP 服务器表明 OAuth 可用或必须使用 OAuth 时,ChatGPT 才会显示 OAuth 账号关联界面。

要触发工具级 OAuth 流程,必须同时提供元数据(securitySchemes 和资源元数据文档)以及携带 _meta["mcp/www_authenticate"] 的运行时错误。缺少其中任何一项,ChatGPT 都不会为该工具显示账号关联界面。

  1. 发布资源元数据。 MCP 服务器必须在标准 URL(例如 https://your-mcp.example.com/.well-known/oauth-protected-resource)上提供其 OAuth 配置。

  2. 使用 securitySchemes 描述每个工具的身份验证策略。 为每个工具声明 securitySchemes,以便 ChatGPT 确定哪些工具需要 OAuth,哪些可以匿名运行。即使整个服务器使用相同的策略,也请逐个工具声明。使用服务器级默认值会增加日后单独调整工具策略的难度。

    目前支持以下两种方案类型。您可以同时列出两种类型,表示身份验证为可选项:

    • noauth:工具允许匿名调用,ChatGPT 可以立即运行它。
    • oauth2:工具需要 OAuth 2.0 访问令牌。请列出您将请求的授权范围,以便授权确认界面准确显示所需权限。

    如果完全省略此数组,工具将继承服务器声明的默认方案。同时声明 noauth 和 oauth2 表示 ChatGPT 可以先匿名调用工具,关联账号后即可使用需要额外权限的功能。无论您向客户端声明哪种方案,服务器仍必须在每次调用时验证令牌、授权范围和受众。

    示例:支持可选身份验证的公开工具

    import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { z } from "zod";
    
    const server = new McpServer({ name: "auth-example", version: "1.0.0" });
    
    server.registerTool(
      "search",
      {
        title: "Public Search",
        description: "Search public documents.",
        inputSchema: {
          q: z.string(),
        },
        outputSchema: {},
        _meta: {
          securitySchemes: [
            { type: "noauth" },
            { type: "oauth2", scopes: ["search.read"] },
          ],
        },
      },
      async ({ q }) => {
        return {
          content: [{ type: "text", text: `Results for ${q}` }],
          structuredContent: {},
        };
      }
    );

    示例:需要身份验证的工具

    import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { z } from "zod";
    
    const server = new McpServer({ name: "auth-example", version: "1.0.0" });
    
    server.registerTool(
      "create_doc",
      {
        title: "Create Document",
        description: "Make a new doc in your account.",
        inputSchema: {
          title: z.string(),
        },
        outputSchema: {},
        _meta: {
          securitySchemes: [{ type: "oauth2", scopes: ["docs.write"] }],
        },
      },
      async ({ title }) => {
        return {
          content: [{ type: "text", text: `Created doc: ${title}` }],
          structuredContent: {},
        };
      }
    );
  3. 在工具处理函数中检查令牌,并返回 _meta["mcp/www_authenticate"],以便在需要时让 ChatGPT 触发身份验证界面。请检查令牌,验证签发者、受众、有效期和授权范围。如果没有有效令牌,请返回包含 _meta["mcp/www_authenticate"] 的错误结果,并确保其值同时包含 error 和 error_description 参数。完成步骤 1 和 2 后,这段 WWW-Authenticate 质询内容就会触发工具级 OAuth 界面。如果质询要求重新授权,您的身份提供方可以在该流程中保留用户现有的登录上下文。

    示例

    {
      "jsonrpc": "2.0",
      "id": 4,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "Authentication required: no access token provided."
          }
        ],
        "_meta": {
          "mcp/www_authenticate": [
            "'Bearer resource_metadata=\"https://your-mcp.example.com/.well-known/oauth-protected-resource\", error=\"insufficient_scope\", error_description=\"You need to login to continue\"'"
          ]
        },
        "isError": true
      }
    }