发起 MCP OAuth

POST /api/v1/cloud/oauth/start 为 MCP 服务器发起 OAuth 授权流程。CAS 会发现服务器的 OAuth metadata、准备 PKCE，并返回服务商授权地址。服务商跳转到 CAS callback 后，CAS 使用 authorization code 换取 token，并将 mcp_oauth Credential 保存到指定 Vault。

请求头

头部	必选	说明
`Authorization`	是	`Bearer $QODER_ACCESS_TOKEN`
`Content-Type`	是	`application/json`

请求体

字段	类型	必选	说明
`vault_id`	string	是	CAS 保存授权结果的 active Vault
`mcp_server_url`	string	是	用于 OAuth metadata discovery 和后续 Credential 匹配的 MCP server URL
`client_id`	string	否	预先注册的 OAuth client ID。省略时，如果 authorization server 声明了 registration endpoint，CAS 会执行 dynamic client registration
`client_secret`	string	否	所传 `client_id` 的 secret。使用 confidential client 时应和 `client_id` 一起传入

protocol、scope 和 redirect_uri 不是该接口的请求字段。CAS 会从服务端 metadata 发现 OAuth endpoints 和 scopes，并始终使用服务端配置的 callback URL。

请求示例

curl -X POST https://api.qoder.com/api/v1/cloud/oauth/start \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_id": "vault_019e5cdb9c3f71c3b6505eba937a40b4",
    "mcp_server_url": "https://mcp.linear.app/mcp",
    "client_id": "",
    "client_secret": ""
  }'

响应示例

HTTP 200 OK

{
  "authorization_url": "https://auth.example.com/authorize?client_id=cloud-agent&code_challenge=...&code_challenge_method=S256&redirect_uri=...&response_type=code&state=...",
  "state": "65eec7b8e79aa61c249d971678cf9201",
  "callback_origin": "https://api.qoder.com"
}

字段	类型	说明
`authorization_url`	string	需要在浏览器中打开的服务商授权地址
`state`	string	不透明的短期 OAuth state，仅用于关联 popup callback
`callback_origin`	string	浏览器 callback message 的预期来源 origin

完成授权

在浏览器窗口中打开 authorization_url。
用户在 OAuth 服务商页面批准访问。
服务商跳转到 CAS 写入的 callback URL。callback URL 由服务端配置，不能通过该请求覆盖。
CAS 校验并消费一次性 state，使用 code 换取 token，然后在 vault_id 下创建 mcp_oauth Credential。
Callback 页面向 opener 发送 oauth_callback message。也可以通过列出 Vault Credential 获取新 Credential ID；密文不会返回。

该流程要求服务商支持 PKCE S256。未传 client_id 且服务商声明 registration endpoint 时，CAS 会动态注册 public OAuth client。

浏览器跳转快捷接口

GET /api/v1/cloud/oauth/authorize 接受 query 参数 vault_id、mcp_server_url 和 client_id，发起同一流程并以 HTTP redirect 跳转到服务商。需要 client secret 时应使用 POST /oauth/start，不要把密文放在 URL 中。

错误码

HTTP	type	触发条件
400	`invalid_request_error`	缺少必填字段、Vault 非 active、metadata discovery 或 dynamic registration 失败，或服务商不支持必需的 PKCE/token authentication 行为
401	`authentication_error`	PAT 或 SAT 缺失、无效或已过期
404	`not_found_error`	Vault 不存在或不可访问
409	`conflict_error`	Vault 非 active，或 callback 保存 Credential 时该 MCP URL 已存在 active Credential

​请求头

​请求体

​请求示例

​响应示例

​完成授权

​浏览器跳转快捷接口

​错误码

请求头

请求体

请求示例

响应示例

完成授权

浏览器跳转快捷接口

错误码