如何把使用 OAuth 2.1 的 MCP 服务器接入 Kortix 连接器-迪斯科星球

如何把使用 OAuth 2.1 的 MCP 服务器接入 Kortix 连接器

【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress

如果你的 MCP 服务器通过 OAuth 2.1（授权码 + PKCE）做鉴权，本文说明如何在 Kortix 中把它声明为一个provider: mcp的连接器，完成授权，并验证连接可用。整个过程不需要在服务器提供方手工创建 OAuth 应用——只要服务器支持动态客户端注册（RFC 7591），Kortix 会自动注册自己作为客户端。前提是你已经拥有一个 Kortix 项目，且可以在项目中维护kortix.yaml。

Kortix 的 OAuth 2.1 发现链

接入之前先弄清楚 Kortix 探测服务器的顺序，文档中定义的完整流程如下：

未认证的探测请求返回401，并带WWW-Authenticate: Bearer resource_metadata="…"；
Kortix 到该 URL（或/.well-known/oauth-protected-resource）读取受保护资源元数据（RFC 9728）；
Kortix 读取该资源声明的第一个授权服务器的授权服务器元数据（RFC 8414 或 OpenID Connect discovery）。

如果授权服务器声明了registration_endpoint，Kortix 会按 RFC 7591 把自己注册为 OAuth 客户端，界面只剩一个Connect按钮——你不需要创建任何应用，也不需要复制 client ID 或 secret。随后 Kortix 运行 Authorization Code + PKCE（S256），并通过resource参数（RFC 8707）把令牌绑定到该服务器。

另外两点安全行为：

Kortix 把每个连接绑定到签发它的授权服务器。当回调携带iss参数（RFC 9207）时，若与记录的 issuer 不匹配，Kortix 在兑换前就拒绝该 code；
Kortix 维护 MCP 会话：按需执行initialize和notifications/initialized，之后的调用携带Mcp-Session-Id。不回会话的服务器永远看不到握手。

来源：connectors.mdx。

从仪表盘接入（主路径）

这是文档给出的最短操作路径，适合交互式接入：

打开项目，进入Connectors页，选择目标应用（连接器）；
选择连接范围：Project表示共享的项目连接，User表示由发起操作的成员持有；
进入该连接器，选择Add credential，再选择OAuth 2.0标签页；
如果服务器支持动态客户端注册，点击Connect完成授权码流程即可，Kortix 会把连接好的账号存为一条 connection。

从 CLI 接入

仪表盘只是入口之一。同样的流程可以完全在终端里跑完，便于脚本化或从 agent 会话中发起：

1. 在kortix.yaml中声明连接器。mcp提供方必须提供url；transport支持http（默认）或sse，见 manifest 参考：

connectors: - slug: read-ai name: Read AI provider: mcp url: 'https://api.read.ai/mcp' auth: type: bearer

manifest 来自默认分支，连接器在 change request 合并后生效；本地改动可以用kortix ship推送（lint、提交、推分支一次完成），也可以对kortix connectors add等命令加--apply直接改云端项目，见 CLI 文档。

2. 运行授权命令。kortix connectors authorize <slug>端到端完成 OAuth 2.1：发现授权元数据、在服务器支持 RFC 7591 时注册客户端、打印待批准的 URL：

kortix connectors authorize read-ai --json

命令创建 connection、跑完发现链、注册客户端（如支持），返回形如下面的 JSON（文档示例）：

{ "connection_id": "7b1a16b2-...", "registered": true, "scopes": ["openid", "offline_access", "mcp:execute", "meeting:read"], "authorization_url": "https://authn.read.ai/oauth2/auth?response_type=code&...", "expires_at": "2026-08-19T14:48:26.345Z" }

把authorization_url交给实际使用者，由其在浏览器中批准。

3. 检查授权状态：

kortix connectors authorize read-ai --status

命令在状态为error时以非零码退出，这既是验证方式也是脚本里的失败判定。

常用参数：

--scope "<a b>"：收窄本次请求的 scope；
--client-id <id>/--client-secret <s>：服务器不支持动态客户端注册时使用，填你在该提供方自建应用的凭证；
--device：改用 OAuth 2.0 设备流（RFC 8628），打印 code 和 URL 后轮询直到批准、拒绝或过期；
--success-redirect <url>/--error-redirect <url>：自定义授权成功或失败后的跳转。

SDK 提供等价的四个方法：discoverConnectionOAuth2Resource、registerConnectionOAuth2Client、startConnectionOAuth2Authorization、getConnectionOAuth2Status。

服务器需要预注册客户端时

发现链覆盖不了两种情况，需要手工补信息：

服务器公布了端点但没有registration_endpoint：Kortix 会预填 authorization URL、token URL 和 scopes，你只需输入自己创建的应用的 client ID；
服务器完全没有元数据：所有字段手工填写。

如果授权服务器要求提前登记回调地址，登记这一个（Kortix 云端）：

https://api.kortix.com/v1/connectors/oauth2/callback

自托管部署：给实例一个稳定的公网 URL

自托管时回调 URL 从KORTIX_URL（你的 API 公网 origin）派生。授权服务器按字节比较redirect_uri，所以这个值必须稳定。用零配置 quick tunnel 启动的自托管实例，每次cloudflared重启都会得到一个新的https://<random>.trycloudflare.com主机名：支持动态客户端注册的服务器能自行恢复（下次授权用新 URL 重新注册客户端），但需要预注册 OAuth 应用的服务器不行——你必须在每次重启后更新它允许的 redirect URI。

正确做法是配置命名隧道（设置CLOUDFLARE_TUNNEL_TOKEN和CLOUDFLARE_TUNNEL_HOSTNAME），或把KORTIX_URL指到自己的域名，然后一次性登记：

https://<your-kortix-host>/v1/connectors/oauth2/callback

其中<your-kortix-host>替换为你的 Kortix 公网主机名，其余路径固定。

验证与排查

授权完成后：Kortix 会自动重新拉取连接器的工具目录，连接器无需手动 sync 就脱离error状态；
调用被拒时：会话内连接器调用返回{ ok: false, status: "denied", reason, hint }，kortix connectors ls中未授权的应用显示为needs_auth，对应的reason是connector_not_connected（HTTP 403，含义是“连接器已声明但本会话没有可用连接”）。其他常见reason及含义见 connectors.mdx 的拒调表：connector_not_assigned（403，agent 的connectors:授权未包含它）、connector_disabled（403）、connector_not_found（404）、action_not_found（404）；
会话级绑定：需要指定具体 connection 时，用connector_bindings（键为连接器 slug，值为匹配授权策略的活跃 connection_id），可用GET /projects/{projectId}/sessions/{sessionId}/scope读取当前生效绑定，PUT同一路径可替换，对下一次工具调用生效，无需重启会话。

接入完成后的常规使用：把连接器 slug 加进 agent 的connectors字段（记得connectors_required必须是connectors的子集），会话内用kortix connectors ls和kortix connectors call <slug> <action> '<json-args>'发起调用。

限制与边界

该 OAuth 2.1 流程适用于mcp提供方的远程 MCP 服务器（HTTP 或 SSE）；pipedream提供方的托管 OAuth 走的是另一条流（channel 安装或原生 OAuth2 grant），不在本文范围内；
设备流是 OAuth 2.0 device flow（RFC 8628），与主路径的发现/注册链并存，按 CLI 文档中的--device单独使用；
Kortix 侧的连接器策略（policy.default_mode、sensitive: true等）属于连接器治理，与授权接入是两个独立步骤，接入成功后按需配置即可。

【免费下载链接】agentpressThe open-source AI Management System项目地址: https://gitcode.com/GitHub_Trending/ag/agentpress

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析