Kanbaruu MCP Server

Kanbaruu Guide v1.0.0We will keep expanding this guide over time. If you have a question that is not answered here, please contact us and we will improve the documentation.

Guide

MCP

Kanbaruu exposes a remote MCP server at https://www.kanbaruu.com/api/mcp. It lets external agents read Kanbaruu project data and perform a limited set of write actions without using your browser session or your active workspace in the web UI.

This page is the source of truth for:

• how Kanbaruu MCP authentication works
• which scopes and tools exist today
• the exact values to use in supported MCP clients
• what is not available yet

Client configuration formats change often. The setup blocks below were verified against official client docs on May 3, 2026.

What Kanbaruu MCP is

Kanbaruu MCP is a workspace-bound remote MCP server.

That means:

• one token belongs to exactly one user
• one token belongs to exactly one workspace
• one MCP session never switches workspace mid-connection
• one token never grants more access than the Kanbaruu user already has

If you need access to three Kanbaruu workspaces, create three tokens and add three MCP server entries in your client.

Current compatibility

This guide contains direct copy-paste setup for clients whose current official docs document custom remote MCP servers with token headers:

• Claude Desktop
• Claude Code
• OpenClaw
• Cursor
• OpenAI Codex
• VS Code (Cline / Continue)
• OpenCode
• Zed
• Gemini CLI
• Kilo Code

ChatGPT developer mode is not a drop-in connection for the current Kanbaruu MCP server. ChatGPT apps use a different app/connector onboarding flow, while Kanbaruu MCP currently expects a workspace token in the Authorizationheader and does not expose OAuth for ChatGPT app setup yet.

Before you start

Before you create a token, these conditions should be true:

• you are signed in to Kanbaruu
• you are a member of the workspace you want to expose
• the workspace has an active plan
• your Kanbaruu role already allows the actions you want the agent to perform

Kanbaruu is stricter over MCP than in the browser:

• in the web app, inactive workspaces still allow reads
• over MCP, inactive workspaces block both reads and writes

Open Dashboard → Account settings → MCP Access to manage tokens.

If you need a broader dialog walkthrough first, see the Account Settings guide.

Create a token

The Create token form currently includes:

• Token name
• Workspace
• Scopes
  • Read tasks
  • Write tasks
  • Delete tasks
  • Read project members
  • Manage project member roles
• Expiration as an optional date and time

Token creation rules

• at least one valid scope is required
• you can only create a token for a workspace you already belong to
• expiration is optional
• the raw secret is shown only once, immediately after creation

Copy the token now

After you click Create token, Kanbaruu shows the raw token in a Copy token now card.

Important behavior:

• this is the only time the raw token is visible
• Kanbaruu stores only the token hash
• if you lose the token, you cannot reveal it again
• the correct recovery path is: delete the old token and create a new one

Treat the copied token like a password or PAT.

Existing tokens, last-used state, and revocation

Existing tokens stay listed below the form with:

• workspace name
• scope badges
• last-used time
• expiration
• delete action

Deleting a token revokes it immediately. Any MCP client using that token stops working on its next request.

Scope bundles

Use the smallest scope bundle that still lets the client do its job.

• tasks:read: reads tasks and project data. Include this on read-only task tokens.
• tasks:write: creates and updates tasks. Required for create_task and update_task.
• tasks:delete: deletes tasks. delete_task still also requires tasks:write.
• project_members:read: lists project members. Useful for agents that need assignee-aware context.
• project_members:write: changes project roles. This affects only the project role, not the workspace role.

Practical presets:

• read-only assistant: tasks:read + project_members:read
• task editor: tasks:read + tasks:write + project_members:read
• destructive task bot: add tasks:delete
• project role manager: add project_members:write

Do not add tasks:delete unless the client truly needs destructive actions. Kanbaruu intentionally exposes no bulk delete tool, but single-task deletion is still destructive.

Exact server values

These are the canonical connection values for the production Kanbaruu cloud:

TEXT

Transport: Streamable HTTP
URL: https://www.kanbaruu.com/api/mcp
Authentication: Authorization: Bearer <YOUR_KANBARUU_MCP_TOKEN>
Workspace model: one token = one workspace

If you are connecting to a different Kanbaruu environment, replace the base domain and keep the /api/mcp path.

The generic remote MCP shape is:

JSON

{
  "url": "https://www.kanbaruu.com/api/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_KANBARUU_MCP_TOKEN"
  }
}

Quick install with Kanbaruu MCP CLI

For the most common clients, the easiest setup is the Kanbaruu installer CLI.

Supported install targets:

BASH

npx kanbaruu-mcp init --client claude         # Claude Desktop
npx kanbaruu-mcp init --client claude-code    # Claude Code (CLI)
npx kanbaruu-mcp init --client cursor         # Cursor
npx kanbaruu-mcp init --client codex          # OpenAI Codex
npx kanbaruu-mcp init --client vscode         # VS Code (Cline / Continue)
npx kanbaruu-mcp init --client opencode       # OpenCode

The installer writes the client-specific MCP configuration for you, so most users do not need to manually edit JSON files.

Pass token during install

If you already copied the token from Kanbaruu, pass it directly and skip the interactive token prompt:

BASH

npx kanbaruu-mcp init --client claude --token KBR_xxx

Without --token, the installer asks for the token interactively.

For Claude Desktop, Claude Code, Cursor, Codex, VS Code, and OpenCode, prefer the installer commands above. The manual configuration examples below are mainly for review, debugging, or custom setups.

Manual configuration examples

OpenClaw

OpenClaw can store outbound MCP server definitions in its own MCP registry.

CLI setup:

BASH

openclaw mcp set kanbaruu-marketing '{"url":"https://www.kanbaruu.com/api/mcp","headers":{"Authorization":"Bearer YOUR_KANBARUU_MCP_TOKEN"}}'

Equivalent config shape:

JSON

{
  "mcp": {
    "servers": {
      "kanbaruu-marketing": {
        "url": "https://www.kanbaruu.com/api/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_KANBARUU_MCP_TOKEN"
        }
      }
    }
  }
}

Use one named OpenClaw server entry per workspace token.

Cursor

Cursor reads MCP config from project .cursor/mcp.json or global~/.cursor/mcp.json.

JSON

{
  "mcpServers": {
    "kanbaruu-marketing": {
      "url": "https://www.kanbaruu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KANBARUU_MCP_TOKEN}"
      }
    }
  }
}

Recommended shell environment variable:

BASH

export KANBARUU_MCP_TOKEN="paste-your-token-here"

Restart Cursor or reload MCP after saving the file.

Claude Code

The fastest current setup is adding the remote server from JSON:

BASH

claude mcp add-json kanbaruu-marketing '{"type":"http","url":"https://www.kanbaruu.com/api/mcp","headers":{"Authorization":"Bearer YOUR_KANBARUU_MCP_TOKEN"}}' --scope user

Equivalent server JSON:

JSON

{
  "mcpServers": {
    "kanbaruu-marketing": {
      "type": "http",
      "url": "https://www.kanbaruu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KANBARUU_MCP_TOKEN"
      }
    }
  }
}

After adding the server, run:

BASH

claude mcp get kanbaruu-marketing

If you want project-shared config instead of user config, omit --scope userand keep in mind that teammates must never reuse your personal token.

VS Code / GitHub Copilot Agent Mode

VS Code stores MCP servers in mcp.json. For workspace config, use.vscode/mcp.json. For user-wide config, run MCP: Open User Configuration.

Safer example with an input prompt instead of hardcoding the token:

JSON

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kanbaruu-token",
      "description": "Kanbaruu MCP token",
      "password": true
    }
  ],
  "servers": {
    "kanbaruu-marketing": {
      "type": "http",
      "url": "https://www.kanbaruu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:kanbaruu-token}"
      }
    }
  }
}

This same setup pattern is the right starting point for GitHub Copilot agent mode in VS Code.

Zed

Zed can connect to Kanbaruu as a custom remote context server.

Add this to your Zed settings JSON:

JSON

{
  "context_servers": {
    "kanbaruu-marketing": {
      "url": "https://www.kanbaruu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KANBARUU_MCP_TOKEN"
      }
    }
  }
}

After saving, open the Agent Panel settings and confirm the server becomes active.

Gemini CLI

Gemini CLI uses mcpServers in ~/.gemini/settings.json.

For Kanbaruu, use the HTTP transport form:

JSON

{
  "mcpServers": {
    "kanbaruu-marketing": {
      "httpUrl": "https://www.kanbaruu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KANBARUU_MCP_TOKEN"
      },
      "timeout": 15000
    }
  }
}

Gemini CLI namespaces discovered MCP tools automatically. After restart, use/mcp inside Gemini CLI to confirm the server is connected.

Kilo Code

Kilo Code supports remote MCP servers in its current kilo.jsonc config format.

Global file location:

TEXT

~/.config/kilo/kilo.jsonc

Project-level locations:

TEXT

kilo.jsonc
.kilo/kilo.jsonc

Remote Kanbaruu entry:

JSON

{
  "mcp": {
    "kanbaruu-marketing": {
      "type": "remote",
      "url": "https://www.kanbaruu.com/api/mcp",
      "headers": {
        "Authorization": "Bearer {env:KANBARUU_MCP_TOKEN}"
      },
      "enabled": true,
      "timeout": 15000
    }
  }
}

You can also add the same values through Settings → Agent Behaviour → MCP Servers in the extension UI.

What tools Kanbaruu exposes today

Kanbaruu currently exposes tools only. It does not currently expose MCP resources, prompts, or MCP apps.

Current tools:

TEXT

Read
- list_workspace_projects
- get_project
- list_project_columns
- list_project_tasks
- get_task
- list_project_members

Write
- create_task
- update_task
- delete_task
- update_project_member_role

What each tool is for:

• list_workspace_projectslists projects visible to the token user inside the workspace bound to that token
• get_projectreturns one full project, including columns, tasks, tags, preferences, and members
• list_project_columnsreturns light column data for one project
• list_project_tasksreturns flat task data for one project
• get_taskreturns one task by ID
• list_project_membersreturns project members and their project roles
• create_taskcreates one task in one column
• update_taskupdates one existing task
• delete_taskdeletes one task
• update_project_member_rolechanges one project member role to OWNER, ADMIN, EDITOR, or VIEWER

What is not available over MCP today

Kanbaruu MCP is intentionally narrow.

Not exposed today:

• workspace creation, deletion, or workspace switching
• workspace invites and workspace member role changes
• project creation, deletion, or project settings updates
• board settings, rules, tags, and column management
• comments
• attachment upload or file download
• dashboard analytics
• notifications
• GitHub Sync controls

If you need these actions, use the Kanbaruu web UI instead.

How to verify a connection

After you add Kanbaruu to a client:

1. restart the MCP client or reload MCP servers
2. open that client's MCP tool list or server list
3. check that kanbaruu-marketing or your chosen server name shows as active
4. confirm that the tool list contains Kanbaruu tool names
5. ask the client to list workspace projects

Good first prompt:

TEXT

List the Kanbaruu projects available through the kanbaruu-marketing MCP server.

Then go back to MCP Access in Kanbaruu and confirm that the token'sLast used timestamp updated.

If Last used stays empty, your client is not reaching Kanbaruu with a valid token yet.

Example payloads

create_task

Valid priority values are:

TEXT

NONE
LOW
MEDIUM
HIGH
CRITICAL

Example input:

JSON

{
  "title": "Finalize MCP rollout guide",
  "description": "Document supported clients and troubleshooting steps.",
  "priority": "MEDIUM",
  "columnId": "col_backlog_01",
  "projectId": "proj_docs_01",
  "assigneeIds": ["user_123"],
  "tagIds": ["tag_docs", "tag_internal"],
  "startAt": "2026-05-03T09:00:00.000Z",
  "endAt": "2026-05-06T17:00:00.000Z",
  "goals": {
    "create": [
      {
        "text": "Write setup blocks",
        "position": 0
      },
      {
        "text": "Add troubleshooting section",
        "position": 1
      }
    ]
  }
}

Rules the server enforces:

• columnId must belong to the same projectId
• all tagIds must already belong to that project
• all assigneeIds must already be project members
• dates must be ISO datetime strings or null

update_task

update_task takes taskId plus a patch object. Include only the fields you want to change.

Example patch:

JSON

{
  "title": "Finalize MCP guide and verify all clients",
  "priority": "HIGH",
  "assigneeIds": ["user_123", "user_456"],
  "tagIds": ["tag_docs", "tag_priority"],
  "startAt": "2026-05-03T09:00:00.000Z",
  "endAt": "2026-05-07T17:00:00.000Z",
  "goals": {
    "create": [
      {
        "text": "Verify Gemini CLI config",
        "position": 2
      }
    ],
    "update": [
      {
        "id": "goal_abc",
        "completed": true
      }
    ],
    "delete": [
      {
        "id": "goal_old"
      }
    ]
  }
}

update_project_member_role

This changes the project role only.

Example input:

JSON

{
  "projectId": "proj_docs_01",
  "userId": "user_456",
  "role": "EDITOR"
}

This does not change the user's workspace role.

Security and operational rules

Keep these rules in mind:

• use one token per workspace
• use separate tokens per client whenever possible
• keep delete scope off by default
• use expiration for temporary experiments
• rotate tokens after demos, screen shares, or accidental disclosure
• never commit raw tokens into repo files

Kanbaruu also logs MCP write actions for audit purposes.

Troubleshooting

Common server-side error codes:

• UNAUTHORIZED: token missing or invalid. Typical fix: check the bearer header and token value.
• TOKEN_EXPIRED: token passed its expiration. Typical fix: create a new token and reconnect.
• MISSING_SCOPE: token does not include the required scope. Typical fix: create a broader token or reduce the requested action.
• WORKSPACE_PLAN_INACTIVE: workspace plan is not active. Typical fix: reactivate the workspace plan before using MCP.
• FORBIDDEN: your Kanbaruu role is too weak. Typical fix: use a user who already has the needed UI permission.
• NOT_FOUND: referenced project, task, column, or member does not exist. Typical fix: refresh IDs from a read tool and try again.
• INVALID_COLUMN: column does not match the given project. Typical fix: use a column from the same project.
• INVALID_TAGS: one or more tag IDs are wrong for that project. Typical fix: reload the project's tags and retry.
• INVALID_ASSIGNEES: one or more assignee IDs are not project members. Typical fix: add members in Kanbaruu first or remove those assignees.

Fastest debug sequence:

1. confirm the token exists in MCP Access
2. confirm Last used updates
3. confirm the workspace still has an active plan
4. confirm the token scopes match the action
5. confirm the user behind the token already has the same permission in the web UI

If you want to keep the integration low-risk, start with a read-only token and add write scopes only after the client proves it can correctly read your workspace structure.