MCP OAuth Setup
OAuth is the safest default for user-driven MCP clients because the connection follows the user's current Kravos.ai access.
MCP OAuth Setup
OAuth is the safest default for user-driven MCP clients because the connection follows the user's current Kravos.ai access.
Use OAuth when a person is operating a desktop or editor client. Use an org API key when the integration is a service account or CI job.
Automatic OAuth Discovery
Most people do not need this section. Enter https://mcp.kravos.ai/api/v1 in an MCP client and complete the consent screen it opens.
The .well-known URL is not a directory. It is a standard web convention for a small, machine-readable metadata document. MCP clients use it to learn two things automatically:
- the MCP resource URL they are connecting to
- the Kravos.ai OAuth server that handles sign-in and consent
The MCP host exposes that metadata at both of these URLs:
https://mcp.kravos.ai/.well-known/oauth-protected-resource
https://mcp.kravos.ai/api/v1/.well-known/oauth-protected-resource
Custom clients can request either URL and receive JSON that identifies https://mcp.kravos.ai/api/v1 as the resource and https://kravos.ai as its authorization server.
The metadata points clients to the authorization server. Hosted Kravos.ai serves authorization metadata from:
https://kravos.ai/.well-known/oauth-authorization-server
It advertises these endpoints:
| Endpoint | Purpose |
|---|---|
/api/oauth/platform/register | Dynamic client registration. |
/api/oauth/platform/authorize | Browser authorization and consent. |
/api/oauth/platform/token | Authorization-code and refresh-token exchange. |
/api/oauth/platform/revoke | Revoke an access or refresh token family. |
Supported OAuth Flow
Platform MCP supports:
- authorization code flow
- PKCE with
S256 - dynamic client registration
token_endpoint_auth_method: none- refresh-token rotation
- bearer access tokens
It does not require a client secret for dynamically registered clients.
Dynamic Client Registration
Register the MCP client before starting authorization if the client does not do this automatically.
POST https://kravos.ai/api/oauth/platform/register
Content-Type: application/json
{
"client_name": "Example MCP Client",
"redirect_uris": ["http://localhost:3333/callback"]
}
The response includes a generated client_id, the registered redirect URIs, supported grant types, and whether the client is verified.
Dynamic registration is rate limited. If a client retries too often, Kravos.ai returns slow_down with status 429.
Redirect URIs must be one of:
- HTTPS
- HTTP loopback, such as
http://localhost:3333/callback - allowed private-use schemes, including reverse-domain schemes such as
com.example.app://callback
javascript:, data:, file:, and reserved schemes are rejected.
Authorization Request
Send the user to the authorization endpoint with PKCE:
https://kravos.ai/api/oauth/platform/authorize?response_type=code&client_id=mcp_client_...&redirect_uri=http%3A%2F%2Flocalhost%3A3333%2Fcallback&code_challenge=...&code_challenge_method=S256&resource=https%3A%2F%2Fmcp.kravos.ai%2Fapi%2Fv1&scope=docs%3Aread%20agents%3Aread
Important behavior:
resourcemust match the Platform MCP resource URL exactly after trailing-slash normalization.- the user must be signed in to Kravos.ai
- inactive users, memberships, or tenants cannot authorize
- consent expires after 10 minutes
- unsupported scopes are rejected before consent
Scopes
You can request broad scopes or exact MCP permissions.
| Scope | Expands to |
|---|---|
read | all normal permissions ending in :read |
write | all normal :write permissions plus chat:write |
| exact permission | one permission such as sources:write or api_keys:read |
If no scope is requested, Kravos.ai grants docs:read.
Destructive scopes such as sources:delete are separate from write. They are only grantable by admin roles and should be requested only for clients that need destructive tools.
Role And Agent Access Reduction
OAuth cannot grant more than the current user can use.
| Current user access | Result |
|---|---|
| Admin or superadmin with all-agent access | Can grant normal permissions and destructive permissions. |
| Support role | Reduced to the Operator-style normal permissions; destructive permissions are removed. |
| Assigned-agent access | Reduced to safe agent tools: agent read/config, chat, playground, and docs. Agent-related resource grants are narrowed to assigned active agents. |
If reduction removes every requested scope, the token exchange fails with invalid_grant.
Token Exchange And Refresh
After consent, exchange the code with the same client_id, redirect_uri, and PKCE verifier.
Access tokens use the mcp_at_... prefix and expire in 3600 seconds. Refresh tokens use the mcp_rt_... prefix and expire after 30 days.
Refresh tokens rotate. Reusing an old refresh token revokes the connection's token family.
Revoke A Connection
Users can revoke their own OAuth connections in MCP Connections → OAuth Connections. Admins can view and revoke tenant connections.
Clients can also call the revocation endpoint:
POST https://kravos.ai/api/oauth/platform/revoke
Content-Type: application/x-www-form-urlencoded
token=mcp_at_...
Revoking any token revokes the whole connection family.
Related Docs
MCP Client Configs
Set up common MCP clients with OAuth or API-key headers.
MCP Permissions
Understand presets, exact permissions, resource grants, and destructive access.