MCP authentication

The KonvoAI MCP server is an OAuth resource server. The WorkOS AuthKit OAuth 2.1 authorization server (hosted at your AuthKit domain) mints the tokens — KonvoAI only verifies them.

Discovery

Unauthenticated requests to /mcp return 401 Unauthorized with a WWW-Authenticate header pointing at protected resource metadata:

GET /.well-known/oauth-protected-resource/mcp

The document includes:

• resource — canonical MCP URL (for example https://api.konvoai.com/mcp)
• authorization_servers — the AuthKit domain (for example https://your-tenant.authkit.app)
• bearer_methods_supported — header

The client discovers the authorization server's metadata directly from the AuthKit domain (/.well-known/oauth-authorization-server), which advertises DCR, CIMD, and PKCE (S256), then runs OAuth 2.1 against it. No custom scopes are requested — access is gated server-side (see below), so the client uses the AuthKit defaults (openid profile email).

Token validation

Access tokens must:

• Verify against the AuthKit authorization server's JWKS (https://<AUTHKIT_DOMAIN>/oauth2/jwks)
• Carry iss equal to https://<AUTHKIT_DOMAIN>
• Include an aud claim equal to the MCP resource URL (RFC 8707 resource indicators — WorkOS binds the resource parameter into aud)

After cryptographic validation, KonvoAI loads your user row (sub → user id) and rejects the request unless MCP server is enabled in Advanced settings. Authorization for each tool is enforced by your organization membership, not by token scopes.

WorkOS dashboard (operators)

Configure once per environment:

1. MCP authorization — Under Connect → Configuration, enable Dynamic Client Registration (DCR) and Client ID Metadata Document (CIMD) so MCP clients can register automatically. This makes the AuthKit domain serve the OAuth 2.1 authorization-server metadata (/oauth2/authorize, /oauth2/token, /oauth2/jwks).

KonvoAI requires one environment variable, AUTHKIT_DOMAIN (the AuthKit domain, e.g. your-tenant.authkit.app), wired into the api service. The resource URL itself comes from PUBLIC_API_URL.