Klaro Cards

Connect to the MCP Server

Step-by-step setup for Claude Desktop, VS Code Copilot, Cursor, and other MCP-compatible agents

  1. What is the MCP Server?
  2. Connect via OAuth (recommended)
    1. In Claude Desktop
    2. In other agents
    3. Reviewing what you granted
  3. Alternative: manual Bearer token
  4. Acting through a workspace
  5. Available Tools
    1. Cards
    2. Links between cards
    3. Comments
    4. Attachments
    5. Dimensions
    6. Boards
    7. Workspaces
    8. Metrics
    9. Projects, people and guides
  6. Troubleshooting

What is the MCP Server?

Klaro Cards exposes its API through the Model Context Protocol (MCP) — an open standard that lets AI agents interact with external tools. The MCP server is called Sia and is available at https://ai.klaro.cards/mcp. It is listed in the public MCP registry, so some clients will find it by name rather than by URL.

If your company uses a dedicated Klaro Cards instance, please:

  1. Check with your sales representative that the MCP server is deployed
  2. Use https://ai.${your-company-deployment-domain}/mcp instead

The easiest way to connect is through OAuth — no token copy-pasting required.

In Claude Desktop

  1. Open Claude → Settings → Connectors → Add custom connector
  2. Enter:
    • Name: Klaro Cards
    • Remote MCP server URL: https://ai.klaro.cards/mcp
  3. Click Add

claude-add-custom-connector.png

Claude will open a browser window and send you to the Klaro consent page:

klaro-oauth-consent-en.png

On that page, you choose:

  • Scope — leave empty to grant access to all your projects, or pick a single project from the dropdown. When a project is selected, you can narrow further to specific workspaces.
  • Permission level:
    • Contributor — create and modify cards only
    • Modeler — cards + dimensions + boards
    • Full access — all resources (use with care)

Click Allow. You're redirected back to Claude, and Klaro tools appear in the connector panel.

In other agents

OAuth setup works the same way in any MCP client that supports Streamable HTTP with OAuth discovery (VS Code Copilot, Cursor, Windsurf, etc.): add a remote MCP server with URL https://ai.klaro.cards/mcp and follow the consent flow in the browser. Copilot registers itself when you ask it to, which is the whole of its setup.

Reviewing what you granted

A grant is not a one-way door. Project settings → Integrations lists every
consent you have given — which application, through which workspace, when it was
made and when it was last used — and lets you revoke one. Reconsenting to the
same application replaces the grant rather than piling a second one beside it.

Alternative: manual Bearer token

Some agents (or older versions) don't support OAuth yet. In that case, use a static Bearer token:

  1. Log into Klaro Cards in your browser
  2. Open Developer Tools (F12) → Network tab, perform any action
  3. Copy the Authorization header from any API request (the part after Bearer )
  4. In your agent's MCP config, set the server URL to https://ai.klaro.cards/mcp with an Authorization: Bearer <token> header

This token inherits your user's permissions — see Using Klaro Cards with AI Agents for best practices on using a dedicated agent user.

Acting through a workspace

This is the one idea worth understanding before the tool list, because it
explains answers that otherwise look wrong.

A project does not look the same from every workspace: which cards exist, which
dimensions they carry and what a new card inherits all depend on the workspace
you are looking through. So most tools take a workspace — its code, like
admins or developers.

  • Codes are defined by the project and cannot be guessed. An agent should call
    get-my-workspaces first.
  • Passing a workspace you have no access to is refused rather than silently
    widened.
  • Ask an agent for "the cards on the pipeline board" and getting fewer than you
    expect usually means it acted through a workspace that hides some of them.

Every tool also declares what it does to the project — whether it only reads,
writes, or destroys — so a well-behaved client can ask you before the
destructive ones.

Available Tools

Once connected, your agent has access to the following tools.

Cards

Tool What it does
search-cards Search for cards using keywords and dimension filters
get-card Get full details of a card
create-card / update-card / delete-card Create, modify or remove a single card
bulk-create-board-cards / bulk-update-board-cards Create or update many cards on a board in one call
bulk-archive-cards / bulk-delete-cards Archive or delete many cards at once
pin-cards / unpin-cards / get-my-pinned-cards Your own pinned cards
Tool What it does
get-card-links What a card is attached to
link-cards / unlink-cards Create or remove a relationship
set-link-description Say what a particular link means

Comments

Tool What it does
get-card-comments Read a card's discussion
add-card-comment / edit-card-comment Write or amend a comment

Attachments

Tool What it does
get-card-attachments List a card's files
presign-upload Ask for a short-lived upload URL — the bytes never pass through the conversation
attach-uploaded-file Attach what was uploaded, optionally as the cover
delete-attachment Remove a file from a card

Dimensions

Tool What it does
get-klaro-dimensions / get-klaro-dimension List dimensions, or detail one
create-dimension / update-dimension Create or reconfigure a dimension
create-dimension-value / add-dimension-values / update-dimension-value Manage a dimension's values, one or many
get-dimensions-installers List the ready-made dimensions you can install

Boards

Tool What it does
list-boards / get-my-boards List boards in a project
get-board / get-board-stories A board's configuration, or the cards on it
create-board / update-board / delete-board Manage a board
set-board-wip-limits Cap how much work a column may hold

Workspaces

Tool What it does
get-my-workspaces The workspaces you may act through — call this first
get-workspaces Every workspace in the project
create-workspace / update-workspace Create or reshape a workspace

Metrics

Tool What it does
list-kpi-catalog The use-case catalog of ready-made metrics
install-kpi / attach-kpi-to-workspace Create a metric, or show an existing one on a workspace
get-workspace-kpis / get-kpi-dashboard Read a workspace's metrics and its statistics page
write-kpi-dashboard-note Leave a written note on the dashboard, explaining what the numbers mean

Projects, people and guides

Tool What it does
get-my-projects / get-project-information Your projects, and one project's details
search-users Search users by name or email
search-guides / get-guide Search these guides and read one — an agent can look up how a feature works before using it

Troubleshooting

Issue Solution
"Unauthorized" error Your OAuth session or token may have expired. Reconnect the connector, or refresh your manual token.
"Project not found" Check the project subdomain. Ask the agent to list your projects first.
"Permission denied" The permission level you granted may be too restrictive. Disconnect and re-authorize with a higher level, or check your workspace roles.
Fewer cards than expected The agent is acting through a workspace that does not show them. Ask it which workspace it used, or name one explicitly.
"Workspace not found" Workspace codes are project-defined. Have the agent call get-my-workspaces rather than guessing.
Agent can't find tools Verify the URL is https://ai.klaro.cards/mcp and transport is Streamable HTTP.
OAuth redirect fails Make sure pop-ups are not blocked for ai.klaro.cards, and that you're logged into Klaro in the same browser.
Go back