OAuth for MCP clients

Authorization discovery, PKCE, scopes and token handling for MCP client implementers.

Kinesis supports browser-based OAuth authorization for the MCP server. API keys remain available for clients that use a static bearer header.

Discover the server

An unauthenticated MCP request returns 401 with a WWW-Authenticate challenge containing resource_metadata. Follow that URL rather than hard-coding deployment-specific authorization endpoints.

For the public service:

Metadata	URL
Protected resource	https://mcp.kinesis.network/.well-known/oauth-protected-resource/mcp
Authorization server	https://portal.kinesis.network/.well-known/oauth-authorization-server
MCP resource identifier	https://mcp.kinesis.network/mcp

The protected-resource document lists the authorization server, resource identifier, supported scopes and bearer-header authentication. The authorization-server document lists the endpoints and client capabilities.

Authorization flow

The supported grant types are authorization_code and refresh_token; the response type is code. PKCE uses S256. Public clients use token endpoint authentication method none. The server advertises dynamic client registration and client ID metadata document support; use the discovery response to select the approach your client implements.

The public endpoint paths are /oauth/authorize, /oauth/token, /oauth/register and /oauth/revoke on the portal origin.

Scopes and token lifetime

OAuth requests use explicit API scope names, such as apps:read, monitoring:read and compute:spend. OAuth does not issue the * full-access wildcard. Request offline_access when your client needs a refresh token.

The current implementation uses ten-minute authorization codes, one-hour access tokens and thirty-day refresh tokens. Use returned expiry values as the authority. Refresh tokens rotate; replace the stored token after refresh and serialize concurrent refresh attempts.

A refresh request may repeat offline_access. Kinesis removes that OAuth-only scope before checking resource permissions. Omitting scope, or supplying only offline_access, retains the issued scopes. A nonempty resource-scope list may narrow the grant but cannot add permissions; ungranted scopes return invalid_scope.

OAuth tokens are scoped to the MCP resource. The REST API does not accept them. Use an API key for REST integrations.

Organization access

A connection acts as its person with their role in each organization. Consent can allow all organizations, including ones joined later, or selected organizations. whoami.limitedToOrgs describes the limit and list_orgs lists reachable organizations. Organization-level actions use the slug as org; project, app and grid actions resolve it from their resource.

Losing membership ends that connection’s access in the organization. A connection limited to chosen organizations cannot create another organization or answer received organization invitations.

Insufficient scope

Kinesis can return an HTTP 403 challenge before a call runs when it can determine that the OAuth connection lacks required scopes. When the scope depends on tool arguments, a tool failure can include an authorization challenge in _meta["mcp/www_authenticate"].

The Organizations release adds members:read, members:write, org:write and audit:read. Existing connections do not gain them through token refresh; the user must approve them again. audit:read is required separately for the audit log and is not implied by org:write.

Read structuredContent.error.requiredScopes, request the appropriate authorization step-up and retry only after the new grant is available. The original user's role on the resource still limits what the connection can do.