workboardworkboard

Kaneo MCP Server

Workboard 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, comments, and labels.

Built-in HTTP endpoint

Every Workboard API instance ships with a Streamable HTTP MCP endpoint. This is the recommended approach for self-hosted deployments.

Point your MCP client at:

https://your-kaneo-instance.com/api/mcp

On first connect, 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: modern 2026-07-28 requests are stateless and self-contained, while 2025-era clients keep the sessionful initialize flow. See MCP 2026-07-28 stateless compatibility for the exact contract, tests, Codex configuration, limitations, and rollback.

Stdio package

The @workboard/mcp package runs a local stdio MCP server and authenticates with Workboard 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 Workboard allows both workboard-cli and workboard-mcp as device auth client IDs.

Install and register

Use the recommended interactive installer:

npx @workboard/mcp

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:

workboard-mcp install --target cursor-user -y

Use --help to see all available targets and flags:

workboard-mcp install --help

Point to a self-hosted instance

When generating config, pass your Workboard base URL:

workboard-mcp install --target cursor-user -y --api-url https://kaneo.example.com

Or set it via environment variable:

Variable Description
KANEO_API_URL Workboard API origin. Default: http://localhost:1337. Do not include /api.
KANEO_MCP_CLIENT_ID Device auth client ID. Default: workboard-mcp.

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 Workboard access, the MCP server:

  1. Requests a device code from Workboard
  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 ~/.config/workboard-mcp/credentials.json

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, create_task, update_task, delete_task, move_task, update_task_status, update_task_assignee, update_task_due_date, list_task_activity
  • Time entries: list_task_time_entries, get_time_entry, create_time_entry, update_time_entry
  • Comments: list_task_comments, create_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

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.

Debugging

To run the stdio server directly:

npx @workboard/mcp serve

When running from source in this monorepo:

pnpm --filter @workboard/mcp run build
pnpm --filter @workboard/mcp run start