Start MCP OAuth

POST /api/v1/cloud/oauth/start Starts an OAuth authorization flow for an MCP server. CAS discovers the server's OAuth metadata, prepares PKCE, and returns the provider authorization URL. After the provider redirects to the CAS callback, CAS exchanges the authorization code and stores an mcp_oauth credential in the selected Vault.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer $QODER_ACCESS_TOKEN`
`Content-Type`	Yes	`application/json`

Request body

Field	Type	Required	Description
`vault_id`	string	Yes	Active Vault in which CAS will store the resulting credential
`mcp_server_url`	string	Yes	MCP server URL used for OAuth metadata discovery and later credential matching
`client_id`	string	No	Pre-registered OAuth client ID. If omitted, CAS uses dynamic client registration when the authorization server advertises it
`client_secret`	string	No	Secret for the supplied `client_id`. Provide these two fields together for a confidential client

protocol, scope, and redirect_uri are not request fields. CAS discovers the OAuth endpoints and scopes from server metadata and always uses its configured callback URL.

Example request

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": ""
  }'

Example response

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"
}

Field	Type	Description
`authorization_url`	string	Provider URL to open in a browser
`state`	string	Opaque, short-lived OAuth state. Use it only to correlate the popup callback
`callback_origin`	string	Origin from which the browser callback message is expected

Complete the authorization

Open authorization_url in a browser window.
The user approves access at the OAuth provider.
The provider redirects to the callback URL embedded by CAS. The callback URL is service-configured and cannot be overridden by this request.
CAS validates and consumes the one-time state, exchanges the code for tokens, and creates an mcp_oauth credential in vault_id.
The callback page sends an oauth_callback message to its opener. You can also list the Vault's credentials to retrieve the new credential ID; secret values are never returned.

The flow requires PKCE S256. When no client_id is supplied and the provider advertises a registration endpoint, CAS dynamically registers a public OAuth client.

Browser redirect shortcut

GET /api/v1/cloud/oauth/authorize accepts vault_id, mcp_server_url, and client_id as query parameters, starts the same flow, and responds with an HTTP redirect to the provider. Use POST /oauth/start when a client secret is required; do not place secrets in a URL.

Errors

HTTP	Type	Trigger
400	`invalid_request_error`	Required field missing, Vault inactive, metadata discovery or dynamic registration failed, or the provider does not support required PKCE/token authentication behavior
401	`authentication_error`	PAT or SAT missing, invalid, or expired
404	`not_found_error`	Vault does not exist or is not accessible
409	`conflict_error`	Vault is not active, or an active credential for the MCP URL already exists when the callback stores the credential

​Headers

​Request body

​Example request

​Example response

​Complete the authorization

​Browser redirect shortcut