Endpoint and authentication
The HTTP endpoint is/api/mcp. Every request requires a bearer token that Kaneo can resolve to an authenticated user. Tools make internal API requests as that user, so workspace permissions still apply.
OAuth clients discover Kaneo’s authorization server, register a public client, and use the authorization code flow with PKCE (S256). The user must approve the connection in Kaneo. The token endpoint supports the authorization-code grant; it does not advertise a refresh-token grant.
The discovery URLs at the public API origin are:
/.well-known/oauth-protected-resource/api/mcp/.well-known/oauth-authorization-server/api
/api/.well-known/. Preserve discovery routes as well as /api/mcp when configuring your reverse proxy.
Supported transports
Let your client negotiate its supported protocol. No Kaneo environment switch is needed to choose between HTTP protocol versions.
Neither HTTP flow needs session affinity. A request can reach any API replica,
including after a replica restarts. Kaneo accepts
Mcp-Session-Id headers issued
by older versions on authenticated POSTs, but does not retain their session
state. OAuth registration and pending authorization state are stored in
PostgreSQL and shared between API replicas.
Reverse proxy and internal requests
Forward the client’s authorization, content type, and MCP headers unchanged. Allow streaming responses for clients that use them. HTTP MCP tools reach Kaneo’s API throughKANEO_INTERNAL_API_URL, which defaults to http://127.0.0.1:1337. This is a server-side address, separate from the public URL used for discovery and sign-in. Set it only when that loopback address does not reach the API from its own process.
Troubleshooting
A tool can also fail because the user lacks permission or its arguments do not match the project. Call
list_project_columns before assigning a status and list_workspace_members before assigning a user.
OAuth request limits
The HTTP OAuth endpoints accept bodies up to 32 KiB and URLs up to 8 KiB. Client registration accepts at most 10 redirect URIs. Request bodies must arrive within five seconds. Each API process allows up to 16 concurrent requests in each of the registration, authorization, and token endpoint groups. Instances sharing a database also share OAuth storage and issuance limits:
When capacity is exhausted, the endpoint returns HTTP 429 with
Retry-After.
Clients should wait before retrying. Existing, unexpired entries are retained;
an approval that cannot issue a code leaves its authorization request available
for retry until it expires. Expired entries are cleaned up in bounded batches
when new state is created, so a previously oversized store may need multiple
attempts before accepting new entries. These limits complement reverse-proxy
connection and request limits for internet-facing installations.