API and MCP

API base URL: https://kanbanana.app (all REST endpoints use the prefix https://kanbanana.app/api/public/v1).

The REST API requires an API key in the Authorization: Bearer <key> header. Create keys in account settings (Pro or Team plan required).

curl -H "Authorization: Bearer fb_xxxxxxxxxxxxxxxxxxxx" \
  https://kanbanana.app/api/public/v1/boards

The REST specification comes from the same operation definitions used by this page. MCP tool schemas come from the live server manifest, so names, types and null handling match the /mcp endpoint. Import them into Postman, Swagger UI, a client generator or an AI assistant.

• REST (OpenAPI 3.1): /api/public/v1/openapiJSONYAML
• MCP tools (JSON Schema): /api/public/v1/mcp-toolsJSONYAML

curl https://kanbanana.app/api/public/v1/openapi | jq .paths

Kanbanana provides an MCP server that lets AI assistants (such as Claude, ChatGPT and Cursor) read boards and manage cards through OAuth. MCP endpoint: https://kanbanana.app/mcp (server kanbanana, version 0.2.1).

How to connect: in a web app (Claude or ChatGPT), add a custom connector using the URL above. Authentication uses OAuth 2.1 with dynamic client registration, so you do not need a client ID or API key. After signing in, grant consent. Tools then act on your behalf with the same permissions as your account in Kanbanana.

In clients with a configuration file (Cursor or Claude Desktop), use the same URL:

{
  "mcpServers": {
    "kanbanana": {
      "url": "https://kanbanana.app/mcp"
    }
  }
}

The tool descriptions and schemas below come directly from the live MCP server definitions. Pass parameters in the arguments field of a tools/call request; MCP does not use an HTTP request body.

Fields in MCP responses

Results are returned in structuredContent.result. list_boards returns boards[] with fields id, name, description, accent, icon, template, created_at, updated_at. get_board returns board (without created_at), columns (id, name, color, position, wip_limit, is_done_column), cards, labels and cardLabels.

• REST API: 1,000 requests per hour per API key.
• Write operations (POST/PATCH/DELETE): an additional 60 requests per minute per key.
• Requests without a valid key: 60 per hour per IP address.
• MCP endpoint /mcp: 600 requests per hour per token (or per IP when no token is provided).

Every REST response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. When the limit is exceeded, the API returns 429 with Retry-After in seconds.

Error codes and retries

REST API errors use a consistent JSON format. The retryable field tells you whether to retry the request with exponential backoff.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Try again later.",
    "retryable": true,
    "retryAfter": 42
  }
}

The MCP endpoint returns transport errors in JSON-RPC format: -32029 for rate limits and -32603 for server errors. Both include retryable and retryAfter in data. Domain errors (such as an unknown ID) return as tool results with isError: true and a structured code:

{
  "isError": true,
  "structuredContent": {
    "result": {
      "error": { "code": "not_found", "message": "No board found for the given boardId.", "retryable": false }
    }
  }
}

• not_found — unknown or inaccessible boardId, cardId or columnId (equivalent to REST 404). Do not retry.
• unauthenticated — missing or invalid OAuth token. Reconnect the connector.
• forbidden — insufficient board or card permissions. Do not retry.
• invalid_request — invalid input. Do not retry.
• internal_error — server error; retryable: true. Retry with backoff.

Example: create a card

curl -X POST \
  -H "Authorization: Bearer fb_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"columnId":"column-uuid","title":"New card","priority":"high"}' \
  https://kanbanana.app/api/public/v1/boards/board-uuid/cards