Skip to main content
Kaneo supports the Model Context Protocol (MCP) in two ways:
  1. Built-in HTTP endpoint: every Kaneo instance exposes /api/mcp out of the box. No extra setup, no extra process.
  2. Stdio package (@kaneo/mcp): the official Kaneo MCP package on npm, a local stdio server for clients that prefer stdio transport.
Both offer the same tools for managing workspaces, projects, tasks, custom fields, comments, and labels. To work with Kaneo from a terminal or a shell script instead, use the Kaneo CLI.

​
Built-in HTTP endpoint

Every Kaneo API instance ships with a Streamable HTTP MCP endpoint. This is the recommended approach for self-hosted deployments. Point your MCP client at:
With an OAuth-capable client, you will be redirected to Kaneo to sign in and explicitly approve the MCP client. After approval, all MCP tools run as your authenticated user. The endpoint implements OAuth 2.1 with PKCE for authentication. Discovery metadata is available at:
  • /.well-known/oauth-protected-resource/api/mcp
  • /.well-known/oauth-authorization-server/api
The endpoint serves both MCP protocol eras without server-side sessions. Modern 2026-07-28 requests are self-contained; 2025-era clients still send initialize, but Kaneo does not issue a session ID. See MCP protocol reference for transport behavior, proxy requirements, and request limits.

​
Stdio package

The @kaneo/mcp package runs a local stdio MCP server and authenticates with Kaneo using device authorization. Use this when your MCP client requires stdio transport.

​
Prerequisites

  • Node.js 24 or newer
  • A running Kaneo API
  • Access to the Kaneo web app to approve device login
By default, self-hosted Kaneo allows both kaneo-cli and kaneo-mcp as device auth client IDs.

​
Install and register

Use the recommended interactive installer:
The installer lets you choose where to register the server configuration:
  • Cursor (user-wide)
  • Cursor (project-level)
  • Claude Desktop
  • Custom JSON config path
You can also run the explicit install command:
Use --help to see all available targets and flags:

​
Point to a self-hosted instance

When generating config, pass your Kaneo base URL:
Or set it via environment variable: If you override KANEO_MCP_CLIENT_ID, make sure it is included in DEVICE_AUTH_CLIENT_IDS.

​
Authentication flow

On the first tool call that needs Kaneo access, the MCP server:
  1. Requests a device code from Kaneo
  2. Prints a verification URL and user code
  3. Opens the browser when possible
  4. Polls until you approve sign-in
  5. Stores credentials in $XDG_CONFIG_HOME/kaneo-mcp/credentials.json, or ~/.config/kaneo-mcp/credentials.json when XDG_CONFIG_HOME is unset

​
Available tools

Both the HTTP endpoint and stdio package expose the same tools:
  • Session: whoami, list_workspaces, list_workspace_members, list_notifications
  • Search: search
  • Projects: list_projects, get_project, create_project, update_project, list_project_columns
  • Tasks: list_tasks, get_task, get_task_by_ticket_id, create_task, duplicate_task, update_task, delete_task, move_task, update_task_status, update_task_assignee, update_task_due_date, list_task_activity
  • Custom fields: list_project_custom_fields, get_task_custom_field_values, set_task_custom_field_value
  • Time entries: list_task_time_entries, get_time_entry, create_time_entry, update_time_entry
  • Comments: list_task_comments, create_task_comment, update_task_comment, delete_task_comment
  • Labels: list_workspace_labels, create_label, attach_label_to_task, detach_label_from_task, delete_label
  • Task relations: create_task_relation, get_task_relations, delete_task_relation
Use get_task_by_ticket_id with a key such as KAN-12 to fetch one task directly. If the same key identifies multiple accessible tasks, pass workspaceId or projectId to select one. list_project_columns is worth calling first when setting a status: the column slugs it returns are exactly the values create_task and update_task_status accept. Likewise list_workspace_members resolves the user IDs the assignee tools expect. Time entries have no delete endpoint on the API, so there is no delete_time_entry tool. get_task and list_tasks don’t include custom field values. Call list_project_custom_fields for a project’s field IDs, types, and options, and get_task_custom_field_values for one task’s values. set_task_custom_field_value takes a string, number, or boolean, an array of options for a multiselect field, or null to clear the value. Dates use YYYY-MM-DD.

​
Debugging

To run the stdio server directly:
When running from source in this monorepo: