Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

4.8 KB
Raw Blame
---
title: MCP protocol reference
description: Authentication, transport behavior, and deployment limits for Kaneo’s HTTP MCP endpoint.
---

Use the [MCP setup guide](/core/integrations/mcp) to connect a client. This page is for people operating Kaneo or building an MCP client.

## 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`

The API also serves these under `/api/.well-known/`. Preserve discovery routes as well as `/api/mcp` when configuring your reverse proxy.

## Supported transports

| Client flow | Kaneo behavior |
| --- | --- |
| MCP 2026-07-28 | A fresh server handles each request. No protocol session is retained between requests. |
| Legacy HTTP flow | The client sends `initialize`, but Kaneo returns no `Mcp-Session-Id`. A fresh server handles each POST. |
| Local stdio | The separate `@kaneo/mcp` package uses device authorization and communicates with the Kaneo API. |

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 through `KANEO_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

| Response | What to check |
| --- | --- |
| 401 | Complete OAuth sign-in again and check that the proxy forwards the bearer token. |
| 405 | The HTTP MCP endpoint accepts POST requests; standalone GET streams and DELETE requests are unsupported. |
| 408 | Send the complete request body within five seconds. |
| 413 | Reduce the request body. MCP HTTP accepts at most 1 MiB. |
| 415 | Send JSON with the correct content type. |
| 429 | Wait for `Retry-After` before retrying. |

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.

### MCP request limits

Both HTTP protocol flows accept request bodies up to 1 MiB (1,048,576 bytes), measured from the received bytes rather than trusting `Content-Length`.
The body must arrive within five seconds.
Each tool call accepts up to 10,000 combined object keys and array elements across its arguments, including nested values.
Calls above that budget return a tool result with `isError: true` without calling the Kaneo API.
These limits apply to the HTTP endpoint, not the separate stdio package.

### 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:

| State | Stored entries | New entries per minute | Pending entries per client |
| --- | --- | --- | --- |
| Registered clients | 1,000 | 60 | Not applicable |
| Authorization requests | 10,000 | 300 | 20 |
| Authorization codes | 10,000 | 300 | 20 |

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.