MCP 服务器
MCP Server Registration 让你的组织接入一个使用 Streamable HTTP 的 Remote MCP Server,使基于你的模板构建的 Agent 可以调用它的工具。Registration 属于组织。后端用 Organization API Key 在 /api/v1/org/mcp/servers 下管理它们;组织所有者可以通过 Console API 管理同样的 Registration。User API Key 不能管理或读取 Registration。见认证。
每个 Registration 的授权模式决定由谁持有它的 MCP Authorization,即调用所使用的凭据:由组织为所有 End User 持有一份,或由每个 End User 用自己在该服务上的账号各自持有。
curl -X POST "$BASE_URL/api/v1/org/mcp/servers" \ -H "Authorization: Bearer $ORG_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"displayName":"Orders","endpointUrl":"https://tools.example.com/mcp","authorizationMode":"organization_static_token"}'displayName 在组织内唯一;endpointUrl 是 HTTPS URL,可以被多个 Registration 共用,例如让不同模板使用不同的凭据。Registration 创建后即为 enabled,无需审批。authorizationMode 决定它向服务器发送什么,以及由谁授权:
| 模式 | 发送 | 授权方 |
|---|---|---|
none |
不发送凭据。 | 无需授权:立即可用。 |
organization_static_token |
一个组织 token。 | 你的后端或组织所有者,设置 token。 |
organization_client_credentials |
Agent Service 用你的 OAuth client credentials 获取的访问令牌。 | 你的后端或组织所有者,设置凭据。 |
organization_oauth |
该服务上一个共享账号的访问令牌。 | 用该账号登录的人,通过 OAuth。 |
end_user_static_token |
拥有该 Session 的 End User 的 token。 | 你的后端,为每个 End User 设置。 |
end_user_oauth |
拥有该 Session 的 End User 自己账号的访问令牌。 | 每个 End User 在自己的浏览器中通过 OAuth。 |
所有凭据都以 Authorization: Bearer 发送。授权可用后,会用它的凭据发现服务器的工具目录,因此 End User 的目录列出的是该 End User 能使用的工具;模式 none 在创建 Registration 时即发现目录。一个授权服务于其所有者引用该 Registration 的每个模板和 Session。
在组织模式下,读取返回 Registration 的 authorization:其 state(usable、invalid 或 revoked)、invalidReason、requiredScope、hasCredential 和 catalog,其中 toolNames 列出找到的工具。在 End User 模式下,Registration 的 authorization 读取为 null,组织的 …/authorization 和 refresh-catalog 路由返回 409;你的后端在设置或确认 End User 的授权时收到该授权,授权需求读取报告其状态。Token、client secret 和 OAuth 令牌只能写入,从不出现在读取、事件或模型上下文中。你可以随时替换或撤销凭据,即使有 Turn 正在使用该 Registration;它们的下一次调用会使用当前凭据。
organization_static_token:用{"token": "..."}调用PUT /api/v1/org/mcp/servers/{serverId}/authorization设置或替换 token。organization_client_credentials:用{"clientId": "...", "clientSecret": "..."}调用同一个PUT设置或替换凭据。Agent Service 读取服务器的401质询和 OAuth 元数据,其中指明它的授权服务器(可能在另一台主机上),再用client_credentials授权类型申请令牌,scope 取质询指明的 scope,否则取服务器公布的 scope。将在一分钟内过期的令牌会在下一次调用前续期,因此长时间的 Turn 和 Scheduler 运行可以继续。授权服务器拒绝请求时,授权读取为invalid,invalidReason为token_rejected,直到你设置可用的凭据。
DELETE /api/v1/org/mcp/servers/{serverId}/authorization 撤销任一持有凭据的模式下组织的授权。
通过 OAuth 授权
Section titled “通过 OAuth 授权”在 organization_oauth 和 end_user_oauth 模式下,账号持有人在浏览器中、在该服务自己的同意页面上登录,从不把密码交给平台。Agent Service 是 OAuth 客户端并保管令牌;你的后端只负责发起授权并确认回来的是谁。Agent Service 读取服务器的 401 质询和 OAuth 元数据,申请质询中指定的 scope,没有时申请服务器公布的 scope,并使用 PKCE、以该服务器作为 resource,以及一次性的 state。将在一分钟内过期的访问令牌会在下一次调用前刷新;授权服务器拒绝刷新时,授权变为 invalid,原因为 token_rejected,直到重新授权。
撤销持有 OAuth 令牌的授权(OAuth 或 client credentials 模式)时,如果授权服务器提供撤销功能,也会在授权服务器上撤销这些令牌;授权服务器缓慢或失败都不会延迟这里的撤销。删除 Registration 时,对其每个授权同样如此。
OAuth 客户端
Section titled “OAuth 客户端”Agent Service 向授权服务器出示以下客户端中第一个可用的:
- 你自己在该服务上注册的客户端,在创建或
PATCH时以"oauthClient": {"clientId": "...", "clientSecret": "..."}设置。请把 Agent Service 的回调地址$BASE_URL/api/v1/mcp/oauth/callback加入它的重定向 URI。同意页面随后显示你的客户端名称,读取只返回其clientId。 - Agent Service 的 Client ID Metadata Document,前提是授权服务器支持它。其 URL
$BASE_URL/api/v1/mcp/oauth/client-metadata.json就是客户端 ID,因此它需要 HTTPS 地址,并随该地址变化。 - 否则,Agent Service 通过授权服务器的 Dynamic Client Registration 注册一个客户端,每个 Registration 注册一次。
使用第二种或第三种时,同意页面显示平台名称,你无法设置其他名称;要显示你自己的名称,请提供你自己的客户端。Agent Service 获得的客户端在授权服务器仍接受它时一直沿用。更换 Registration 的客户端会以 client_changed 使其所有授权失效,使颁发给一个客户端的令牌绝不会在另一个客户端下使用,每个所有者都需重新授权;同一 clientId 换用新的 clientSecret 则不会。
如果你未设置客户端,而授权服务器既不接受 Client ID Metadata Document,也不支持 Dynamic Client Registration,发起授权会被拒绝,返回 409 mcp_oauth_unavailable,details.reason 为 client_registration_unsupported。如果无法读取服务器的 OAuth 元数据、它不支持 PKCE,或 Dynamic Client Registration 失败(client_registration_failed),则返回 502 mcp_oauth_unavailable。
允许返回 URL
Section titled “允许返回 URL”由你的后端发起的授权完成后,浏览器会回到你的某个页面。请先注册这些页面:组织的允许列表最多容纳 20 个绝对 https URL(仅 localhost、127.0.0.1 或 [::1] 可用 http),不含凭据、query 或 fragment。PUT 替换整个列表,GET 读取它,组织所有者可以通过 Console API 管理同一个列表。浏览器返回时会再次检查该列表:为之后已被移除的页面发起的授权会失败,不会返回该页面,也不持有任何结果。
curl -X PUT "$BASE_URL/api/v1/org/mcp/oauth/return-urls" \ -H "Authorization: Bearer $ORG_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"returnUrls":["https://app.example.com/integrations/mcp/return"]}'为 End User 授权
Section titled “为 End User 授权”End User 静态 token
Section titled “End User 静态 token”如果你的后端已经持有 End User 在该服务上的 token,可以直接交给 Agent Service:
curl -X PUT "$BASE_URL/api/v1/org/users/$USER_ID/mcp/servers/$SERVER_ID/authorization" \ -H "Authorization: Bearer $ORG_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"token":"<end-user-token>"}'响应是该 End User 的 authorization,owner.kind 为 end_user。在两种 End User 模式下,对同一路径调用 DELETE 都会撤销该 End User 的授权;其他 End User 不受影响。若 userId 不是该组织的普通 End User,返回 404 resource_not_found;处于其他模式的 Registration 返回 409。
End User OAuth
Section titled “End User OAuth”为 End User 授权分为四步:
-
用一个 origin 和 path 与允许列表条目匹配的返回 URL 发起授权;其 query 由你决定,并会被保留。响应携带要展示给 End User 的
authorizationUrl,有效期到expiresAt,即十分钟之后:终端窗口 curl -X POST "$BASE_URL/api/v1/org/users/$USER_ID/mcp/servers/$SERVER_ID/authorization/oauth/start" \-H "Authorization: Bearer $ORG_API_KEY" \-H 'Content-Type: application/json' \-d '{"returnUrl":"https://app.example.com/integrations/mcp/return?state=<your-state>"}' -
End User 打开链接,登录该服务并同意授权。
-
该服务把浏览器送回 Agent Service,Agent Service 兑换授权码并暂存令牌。随后它把浏览器重定向到你的返回 URL,附带
mcpOAuth=pending_confirmation、serverId和一次性的confirmation值;如果 End User 拒绝或兑换失败,则改为附带mcpOAuth=failed、serverId和reason。 -
你的返回页面确认当前登录你的应用的是哪个 End User,并为该 End User 提交该值:
终端窗口 curl -X POST "$BASE_URL/api/v1/org/users/$USER_ID/mcp/servers/$SERVER_ID/authorization/oauth/confirm" \-H "Authorization: Bearer $ORG_API_KEY" \-H 'Content-Type: application/json' \-d '{"confirmation":"<confirmation>"}'响应是该 End User 的
authorization,此时为usable。
之所以需要确认,是因为 Agent Service 无法判断是谁的浏览器给出了同意:任何拿到链接的人都可以用自己的账号登录。没有确认的话,被转发给或被截获到另一个人手中的链接会把那个人的账号绑定到你的 End User,你的 End User 的 Turn 就会使用该账号执行。浏览器回来时你的应用知道是谁登录着,而 Agent Service 只为发起授权时指定的 End User 接受该值。请从你自己的登录状态中取得 End User,绝不要从返回 URL 中取得。
确认之前一切都不可用,令牌也从不离开 Agent Service。该值只能使用一次,无论是否被接受,并在回调后十分钟失效。若该值未知、已使用、已失效、颁发给另一个 End User 或 Registration,或者自发起以来 Registration 的端点、模式或 OAuth 客户端已改变,则以 400 mcp_oauth_confirmation_invalid 拒绝;请重新发起。确认会替换该 End User 持有的任何令牌,在此之前其当前授权保持不变。当某个结果未经确认而失效、被拒绝,或被同一 End User 之后的确认取代时,Agent Service 还会在授权服务器提供撤销功能时撤销其令牌。返回 URL 不在允许列表中时,以 400 validation_error 拒绝,details.reason 为 return_url_not_allowed。
组织 OAuth
Section titled “组织 OAuth”organization_oauth 模式持有一个共享账号。你的后端用相同的步骤为它授权,只是没有 userId:用 {"returnUrl": "..."} 调用 POST /api/v1/org/mcp/servers/{serverId}/authorization/oauth/start,在确认给出同意的人有权授权该共享账号之后,再用 {"confirmation": "..."} 调用 /api/v1/org/mcp/servers/{serverId}/authorization/oauth/confirm。组织所有者也可以通过 Console API 为它授权;此时回调只接受该所有者的浏览器会话,因此之后无需确认。
查看 End User 还需要什么
Section titled “查看 End User 还需要什么”在 End User 的第一个 Turn 之前,可以针对他们可能用来创建 Session 的模板,或他们拥有的 Session,读取每个被引用的 Registration 还需要什么:
curl "$BASE_URL/api/v1/org/users/$USER_ID/agent-templates/$TEMPLATE_ID/mcp-authorization-requirements" \ -H "Authorization: Bearer $ORG_API_KEY"curl "$BASE_URL/api/v1/org/users/$USER_ID/sessions/$SESSION_ID/mcp-authorization-requirements" \ -H "Authorization: Bearer $ORG_API_KEY"该读取使用与 Turn 准入相同的本地状态,因此只有当新 Turn 不会因 MCP 被拒绝时,ready 才为 true。对每个 Registration,registrations 报告其 registrationStatus、authorizationMode、owner(organization 或 end_user)、authorizationStatus(usable、missing、invalid、revoked 或 insufficient_scope)和 satisfiedBy:End User 自己的 token 或 OAuth 授权即可解决时为 end_user,需要组织的凭据或启用该 Registration 时为 organization,已就绪时为 null。Session 可以在其所有者完成授权之前创建。
修改、停用和删除
Section titled “修改、停用和删除”| 方法和路径 | 用途 |
|---|---|
GET /api/v1/org/mcp/servers |
列出组织的 Registration。 |
GET /api/v1/org/mcp/servers/{serverId} |
读取一个 Registration。 |
PATCH /api/v1/org/mcp/servers/{serverId} |
修改 displayName、endpointUrl、authorizationMode 或 oauthClient,并带上最近读取的 expectedServerVersion。 |
POST /api/v1/org/mcp/servers/{serverId}/disable |
停止使用它的新模板保存、Session 创建、新 Turn 和后续调用。 |
POST /api/v1/org/mcp/servers/{serverId}/enable |
重新允许这些操作。 |
POST /api/v1/org/mcp/servers/{serverId}/refresh-catalog |
以请求体 {} 重新发现组织授权的目录。 |
DELETE /api/v1/org/mcp/servers/{serverId} |
删除没有被任何未归档模板引用的 Registration。 |
修改端点或模式会使该 Registration 的每个授权及其目录失效并撤销其凭据,因此凭据永远不会发往另一个服务器;之后请设置新凭据或重新授权。修改显示名称不会如此。刷新后的目录用于之后开始的 Turn。删除会移除 Registration 的授权并销毁其存储的凭据。只要仍有模板引用该 Registration,删除就返回 409 mcp_server_delete_blocked,details.templates 列出每个 templateId 和 templateName;请先移除引用或归档模板。仍引用已删除 Registration 的 Session 会以 409 session_execution_dependency_unavailable 拒绝新 Turn。
在模板中使用 Registration
Section titled “在模板中使用 Registration”在模板的 content.tools.mcp 中以 {"serverId": "<server-id>"} 引用 Registration,并可添加 "toolNames",只向模型提供其中部分工具;见模板。两个模板可以提供同一 Registration 的不同工具,共用它的授权。
每个被引用的 Registration 都是每个新 Turn 的必需依赖。已停用或已删除的 Registration 会以 409 session_execution_dependency_unavailable 拒绝 Turn。若 Registration 用于该 Turn 的授权不可用(从未设置、已被撤销或失效,或被服务器拒绝),Turn 会在开始前以 409 mcp_authorization_required 被拒绝;details.registrations 列出每个这样的 Registration 及其 serverId、owner 和 reason(missing、invalid、revoked 或 insufficient_scope)。在 End User 模式下,这是拥有该 Session 的 End User 的授权。Backend Connection 的 session.send 以 data.reason 报告同一代码,Scheduler 触发也会立即以该代码失败,不再重试。
如果服务器对调用返回 HTTP 401 或 403,或授权在 Turn 运行期间被撤销,该 Turn 会以相同的代码和 details 进入 failed,而不会在缺少该服务器的情况下继续;授权读取为 invalid,invalidReason 为 unauthorized、forbidden 或 insufficient_scope(服务器要求的 scope 记录在 requiredScope 中)。出现 insufficient_scope 后,下一次 OAuth 授权或重新设置的 client credentials 会同时申请已授予的 scope 和 requiredScope,因此只有在工具需要时才授予更多权限;在该授权完成(包括其确认)之前,授权仍读取为 insufficient_scope。重新设置凭据或重新授权后发起新的 Turn 即可,之前的对话会保留。
在 Console 中测试 Template
Section titled “在 Console 中测试 Template”Console 中的 Template Test 会像 End User 的 Turn 一样调用模板的 MCP 服务器。组织模式的 Registration 使用组织的授权。End User 模式的 Registration 使用 Console 所有者自己的 Template Test Identity 的授权,即该所有者的 Test 所使用的隐藏 End User:所有者通过 Console API 为它设置静态 token,或用 OAuth 授权,Console 本身暂未提供相应控件。OAuth 回调只接受该所有者的浏览器会话,因此之后无需确认步骤。Console API 还可以读取对已保存模板进行 Test、或对进行中的 Test 发起后续 Turn 还需要哪些授权。授权不可用的 Test 会被拒绝,返回 409 mcp_authorization_required;Test Turn 期间服务器拒绝凭据会使该 Turn 以 failed 结束。Test 不调用 Connector。
模型看到什么
Section titled “模型看到什么”模型以 mcp_<server>__<tool> 调用每个工具,两部分都由服务器和工具自己的名称派生。不符合要求的工具(例如输入 schema 过大,或 x-mcp-header 声明无效)会被单独排除,服务器的其他工具仍可使用。每次调用前,只把被调用的工具与 Turn 开始时的目录比较:该工具被修改或移除时,这次调用以 mcp_tool_changed 或 mcp_tool_removed 失败,Turn 继续进行。服务器自己的说明会作为不受信任的参考信息提供给模型。
提供资源的服务器还会为模型带来 platform__list_mcp_resources 和 platform__read_mcp_resource,模型用它们把文档带入上下文。图片、音频和其他二进制结果会成为 Session 文件。Agent Service 同样可以连接 2026-07-28 协议和更早的基于握手的版本的服务器,并且不向服务器提供 Elicitation、Sampling 或 Roots:需要它们的调用会以相应原因失败。Agent Service 向 MCP 和 OAuth 服务器发出的每个请求都只发往公网 HTTPS 地址。