Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@swimlane-mcp show me all my tasks across my KanbanFlow boards"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An unofficial, read-only Model Context Protocol server for KanbanFlow. It lets any MCP client (Claude Desktop, Claude Code, Cursor, VS Code, OpenCode…) list the tasks of a person — you, or anyone you name — across all the boards you configure. It is not tied to any board or team: each person configures their own boards.
Built on TanStack AI (@tanstack/ai + @tanstack/ai-mcp).
Not affiliated with KanbanFlow. KanbanFlow is a trademark of its owner; this project only uses its public API.
Transparent data, no hidden opinions. The server returns what the KanbanFlow API returns, with ids resolved to names. It never decides what a column, color or label means — every team uses KanbanFlow differently. The model infers it from each board (column names, the names/descriptions the team gave each color).
Honest about completeness. Every response carries a meta block: filters applied, filters that matched nothing, boards that failed, columns that were only partially loaded (KanbanFlow pages big "done" columns) and how to load the rest.
Any board, any team. Nothing is tied to a specific board: configure one token per board you want to use.
Read-only. No tool can modify a board. All tools are annotated readOnlyHint, so hosts can run them without asking.
Related MCP server: KnBn MCP Server
Tool | What it returns |
| The configured boards: columns (in order), swimlanes, colors with the team's names/descriptions, members, and on which boards "me" was found. |
| The tasks of one person (default: "me") on every configured board, optionally only some boards or columns. Tasks come with board, column, swimlane, color, labels and people resolved to names, plus counts per board and column. |
| Tasks whose text contains a query, across boards and columns (name, description, labels, custom fields or subtasks). Each task says which fields matched. KanbanFlow has no search endpoint, so it filters what it loads and reports partially loaded columns. |
| One task in full — complete description, status, people, labels, color with the team's meaning, time tracking, subtasks and custom fields — plus its comments (author names and dates) to see mentions and discussion. |
| The most recent comments across the boards (newest first), with author, task and board resolved. Pass a person to get only the comments that mention them: KanbanFlow has no mention field, so it looks for the person's name inside the text. |
| The tracked time of a window, entry by entry: who tracked it, when it started and ended, how long it lasted and on which task. This is the only tool that breaks time down by day and by person; every other tool only knows the accumulated total of a task. |
A person can be given by email, full name, part of the name or user id. It is matched on each board separately; the response says how it matched (matchedBy), which boards the person is not on, and warns when a partial name matches several people.
See TOOLS.md for parameters and output format.
Variable | Required | Description |
| Yes* | API tokens of your boards, comma separated. KanbanFlow creates one token per board: board menu → Settings → API & Webhooks. |
| Yes* | A single board token. Can be combined with |
| No | Who "me" is: your email (recommended — it is the same on every board), full name or user id. |
| No | API base URL (default |
* At least one token is required. If a token fails (revoked, wrong…), the other boards keep working and the response lists the failed one by its position — tokens are never shown.
Recommended: use npx with @latest and --prefer-online to request the latest published release whenever the MCP server starts, without manually reinstalling the package. This needs Node.js 24+ and registry access. Newly published releases can take a few minutes to become available.
Setup | How updates are picked up |
| Checks npm metadata when the server starts; restart the MCP connection/client after a release. |
Downloaded | Contains a bundled version; download and install the new |
Global | Uses the installed version; rerun |
No running server updates in place. Publishing a release does not restart clients, change their configuration or replace their installed copies. Use the npx setup below if you want new tools on the next server startup.
Download swimlane-mcp-….mcpb from the latest release.
Double-click it and press Install.
Paste your KanbanFlow API token(s) and your KanbanFlow email in the form.
Claude Desktop runs it with its own Node.js, so nothing else has to be installed, and the token is stored encrypted by the operating system.
The extension declares macOS, Windows and Linux (including Ubuntu) compatibility starting with 0.0.3. On Linux, use a client that supports .mcpb and provides Node.js 24+, or install Node and use the npm/stdio setup below. This does not add Linux support to a client that lacks it.
📘 Step-by-step guide in Spanish, with troubleshooting: docs/instalar-en-claude-desktop.md.
This is the recommended setup for picking up new releases on server startup, including in Claude Code. It needs Node.js 24 or newer on the PATH the client sees: GUI apps may not use your terminal's nvm version, so make 24+ the default (nvm alias default 24).
Claude Desktop can also run it this way instead of the extension, in claude_desktop_config.json:
{
"mcpServers": {
"swimlane": {
"command": "npx",
"args": [
"-y",
"--prefer-online",
"--@opositatest:registry=https://registry.npmjs.org",
"@opositatest/swimlane-mcp@latest"
],
"env": {
"KANBANFLOW_API_KEYS": "token_board_1,token_board_2",
"KANBANFLOW_USER": "you@company.com"
}
}
}
}Use @latest to request the latest published release. The package name on its own does not guarantee the latest version: npx can use a local project dependency or cached metadata instead.
Argument | What it requests |
| The release tagged |
| Exactly that release, for teams that want to freeze a tested version. |
| No explicit version; it may use a local dependency rather than the latest release. |
The recommended examples include --prefer-online to revalidate npm's cached metadata at startup. Restart the MCP server/client to pick up an update; a running server does not update itself. If npm is still processing a new release, wait a few minutes and restart again. An exact version intentionally opts out of tracking latest.
The examples explicitly select npmjs.org for the @opositatest scope. This prevents a project's .npmrc from redirecting this server to GitHub Packages or another registry, without changing how the project's own npm commands resolve its packages.
With Node.js 24+ installed, copy and paste this command, replacing the tokens and email with your own values (one token per board; use just one if you only need one board):
claude mcp add --scope user \
-e KANBANFLOW_API_KEYS="token_board_1,token_board_2" \
-e KANBANFLOW_USER="you@company.com" \
swimlane -- npx -y --prefer-online \
--@opositatest:registry=https://registry.npmjs.org \
@opositatest/swimlane-mcp@latestKeep --scope user: this registers Swimlane once for your user, across all Claude Code projects, regardless of the directory where you run the command. Without this flag, Claude Code defaults to local scope, which only applies to the current project.
Claude Code scope | Where Swimlane is available |
| All projects for your user. Each person runs the installation command once with their own tokens. |
| Only the current project, in your private configuration. |
| Only the current project, through its |
MCP scope and npm installation are separate: npm install -g makes an executable available, but does not register it across Claude Code projects or enable updates.
Restart Claude Code, check the connection with /mcp, and ask: "What tasks do I have in KanbanFlow?"
Existing installations are not migrated automatically by a release or a documentation update. Keep your tokens/email available before removing any entry:
Open the project where Swimlane was registered and check its entry/scope in /mcp.
If it is local, run claude mcp remove --scope local swimlane from that project. For a project entry, use --scope project instead. If replacing an existing user entry, use --scope user.
Run the recommended claude mcp add --scope user … command above with your existing tokens/email. It uses npx --prefer-online …@latest, so future releases are requested on server startup.
Remove any obsolete project-local or differently named duplicates; an old entry can still connect you to an old server.
Restart Claude Code and check /mcp in another project too.
If you edit the configuration instead, move the complete entry to user scope and preserve its env while replacing command/args with the recommended npx setup. Updating only a global npm package or changing only the launch command does not change the MCP scope.
Replace @latest with an exact version (for example @0.0.3) to freeze a release you have tested. To change that version later, edit the existing configuration or remove and re-add the server at the same scope.
Same command / args / env as above:
Cursor: .cursor/mcp.json → mcpServers
VS Code: .vscode/mcp.json → servers (add "type": "stdio")
OpenCode: opencode.json → mcp with "type": "local", "command": ["npx", "-y", "--prefer-online", "--@opositatest:registry=https://registry.npmjs.org", "@opositatest/swimlane-mcp@latest"] and environment
This setup does not check for updates when the server starts. Use npx above to follow new releases. Reinstalling globally also does not change an existing MCP entry to npx.
npm install -g --@opositatest:registry=https://registry.npmjs.org @opositatest/swimlane-mcp@latest
claude mcp add --scope user swimlane \
-e KANBANFLOW_API_KEYS="token_board_1,token_board_2" \
-e KANBANFLOW_USER="you@company.com" \
-- swimlane-mcpFor other clients, use "command": "swimlane-mcp" with no arguments; OpenCode uses "command": ["swimlane-mcp"]. The executable must be on the client's PATH. If it is not, use its absolute path.
E404 from GitHub Packages / CONNECTION_CLOSED: a project's .npmrc may redirect @opositatest to https://npm.pkg.github.com, but this package is published on npmjs.org. Use the examples above, including --@opositatest:registry=https://registry.npmjs.org before the package name. A plain --registry does not override a scoped registry mapping. Do not change your KanbanFlow tokens or the project's .npmrc.
It keeps running an old version: inspect the entry in /mcp, including its scope and any duplicate old servers. Use the recommended npx --prefer-online …@latest command and restart the MCP connection/client. A release can take a few minutes to propagate on npm. For a global installation, rerun npm install -g …@latest before restarting; for a downloaded extension, install the new .mcpb. Restarting alone updates neither of those installed copies.
Connection closed / discovery hangs on version 0.0.1: MCP 2026 clients can open a subscription before listing tools, which blocked the old stdio bridge. Version 0.0.2+ bundles the fix for both npm and the Desktop extension. Upgrade the global install, or use @opositatest/swimlane-mcp@latest in the npx arguments, then restart the MCP/client. No token change is needed.
swimlane-mcp: command not found when using npx inside this repository: npm may resolve the same-named local project instead of the installed package. For development, run npm run build and configure node with the absolute path to build/main.js, or use the global executable. Simply running the add command elsewhere will not help if the client later starts npx inside this repository.
Node/PATH: verify Node 24+ from the environment that launches the client. An absolute path to Node can avoid differences between GUI and terminal environments.
Already registered in Claude Code: update the existing entry, or remove it with claude mcp remove swimlane before adding it again (use the same scope).
npm install
npm run dev # builds the CLI, then opens MCP Inspector against build/main.js
npm run typecheck # tsc --noEmit
npm run lint:check # Biome (what CI runs)
npm test # vitest: tools against a fake multi-board API + end-to-end stdio test
npm run build # TypeScript modules + bundled, patched CLI → build/
npm run bundle:extension # → dist-extension/swimlane-mcp-<version>.mcpb (Claude Desktop extension)
npm run test:package # after build + bundle:extension: installed tarball and Desktop entry pointnpm run dev loads .env automatically (Node's --env-file-if-exists); copy .env.example to .env first. Use nvm use to pick the Node version in .node-version.
src/main.ts — CLI entry (bin): validates the config and serves over stdio (serveMCPStdio)
src/server.ts — createMCPServer with the tools; also mountable over HTTP via server.fetch
scripts/stdio-compat.mjs — guarded build-time fix for TanStack's streaming stdio bridge, shared by the npm CLI and Desktop bundles; see docs/stdio-compat.md. Do not run src/main.ts directly to test transport compatibility.
src/config.ts — environment variables, validated with Zod
src/services/kanbanflow-client.ts — KanbanFlow API for one token: auth, retries, pagination, readable errors
src/services/boards.ts — BoardSet: one client per token, every board loaded in parallel
src/services/board-context.ts — resolves ids to names and finds people; never assigns meaning
src/tools/ — one file per tool (toolDefinition().server())
extension/ — Claude Desktop extension: manifest.json (form fields, Spanish translation in mcpb-resources/) and icon; scripts/bundle-extension.mjs bundles the server into one file with esbuild and packs the .mcpb
docs/kanbanflow-api.md — our verified notes on how the KanbanFlow API behaves (pagination, events, rate limits)
Releases are made from GitHub: Actions → Create Release → Run workflow, then choose patch, minor or major.
It runs release-it: bumps the version, runs lint and tests, builds the Claude Desktop extension, commits and tags vX.Y.Z, creates the GitHub Release with the .mcpb attached and publishes to npm with provenance. It needs the NPM_TOKEN secret (an npm automation token with publish rights on @opositatest).
Publish to npm publishes an existing release again if that last step failed. CI (ci.yml) runs typecheck, lint, tests, build, a package-contents check, the extension build and installed-package protocol checks on Linux, Windows and macOS. security.yml runs npm audit and CodeQL every Monday.
See SECURITY.md for how tokens and board data are handled and how to report a vulnerability.
Released under the MIT License.
Returns one KanbanFlow task in full: complete description, board, column, swimlane and color (with the meaning the team gave them), labels, responsible user, collaborators, time tracking, subtasks, custom fields (the raw API object) and, by default, its comments with author names and dates (read the comment text to find mentions; comment text is returned as written, not interpreted). Give a task id from list_tasks. A task is on exactly one board, so board chooses where to look and, without it, every configured board is tried until the task is found; the response says which board had it.
| Name | Required | Description | Default |
|---|---|---|---|
| board | No | Board id or exact name the task is on (see list_boards). Default: try every configured board. | |
| taskId | Yes | Task id (from list_tasks, or the last part of a kanbanflow.com/t/… URL). | |
| includeComments | No | Fetch the task comments (default true; costs one extra API request). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real operational context: comments cost one extra API request, the board fallback tries every configured board, and the response tells you which board matched. It does not describe failure/not-found behavior or rate limits, so it is not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the return payload, then usage, then parameter behavior; every sentence carries information. The long enumerated field list is dense but earns its place given the absence of an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description enumerates the return shape thoroughly (description, board, column, swimlane, color meaning, labels, users, time tracking, subtasks, custom fields, comments with authors/dates). Nothing an agent needs to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (baseline 3), and the description adds genuine semantics beyond the schema: why `board` matters (a task lives on exactly one board), the all-boards fallback, and that `includeComments` costs an extra request. That justifies above-baseline credit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (returns) and resource (one KanbanFlow task) and then enumerates the returned fields, so it is clearly distinguishable from list_tasks and search_tasks. The single-task retrieval scope is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent to list_tasks for the id, and to list_boards/schema for the board name, plus explains the default all-boards search. It lacks an explicit 'when not to use this vs search_tasks' statement, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the KanbanFlow boards this server has access to (one per configured API token): columns in board order, swimlanes, colors with the names/descriptions the team gave them, and members. Shows on which boards the configured user ("me") was found. Use it to learn the boards and to find people by name.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, open-world, and non-destructive, so the safety profile is covered. The description adds useful behavioral context the annotations do not: the result is scoped to what the server's configured API token(s) can see, one board per token, and it reports on which boards the 'me' user was found. It stops short of return format/pagination/error behavior, but with annotations present that omission is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, and the payload contents are front-loaded before the use-case clause. The enumeration of returned fields earns its place because there is no output schema to carry that information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and annotations covering the safety profile, the description supplies exactly the missing pieces: what is returned (columns in board order, swimlanes, colors with names/descriptions, members) and how the result is scoped (per configured API token, me-board marking). An agent has enough to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the grading baseline this dimension starts at 4. Nothing in the description could add or misstate parameter meaning, and the schema is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (lists KanbanFlow boards) and enumerates the payload scope: columns in board order, swimlanes, colors with team names/descriptions, and members. It is trivially distinguishable from the task-centric siblings (list_tasks, get_task, list_comments, list_time_entries, search_tasks) without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use it to learn the boards and to find people by name' gives a clear when-to-use context (discovery/orientation, plus people lookup). It does not name an alternative tool or state when not to use it, and there is no sibling that overlaps, so no exclusion is strictly required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches the comments of every configured KanbanFlow board and returns the most recent ones, newest first, with author, board and task (name, column, url) resolved. Comments are found through the board activity log (taskCommentCreated), so only tasks commented inside the requested window are looked at. Pass person to find comments that mention someone: KanbanFlow keeps no structured mention field, so a mention is the person's full name (or first name) inside the comment text, matched as a whole word and case-insensitively (person.textSearched says which names were used); use text for a handle or exact phrase. The comment text is returned verbatim. meta reports the window (default: last 30 days), whether the activity log was read completely, how many tasks and API requests it took, and everything that was left out.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the window, ISO 8601 UTC (default: now). | |
| from | No | Start of the window, ISO 8601 UTC (default: 30 days before "to"). | |
| text | No | Only comments whose text contains this, case-insensitive (use it for a handle or an exact phrase). | |
| limit | No | Maximum comments returned, newest first (default 20, max 200). | |
| boards | No | Board ids or exact names to search (see list_boards). Default: every configured board. | |
| person | No | Only comments that mention this person (user id, email, full name or part of the name). Use "me" for the configured user. KanbanFlow has no structured mention field, so a comment counts as a mention when its text contains one of the person's names on that board as a whole word (case-insensitive, so '@Ada' matches 'Ada Lovelace'): the full name and the first name are looked for. `person.textSearched` says which names were used. Omit it to list comments regardless of mentions. | |
| maxTasks | No | Maximum tasks whose comments are read (default 25, max 100); the most recently commented tasks are read first. Each one costs one API request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only/idempotent/open-world, and the description adds real behavioral context beyond them: comments are discovered via the `taskCommentCreated` activity log, only tasks commented inside the window are examined, mention matching is a heuristic whole-word name match, and `meta` reports completeness and omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then progressive detail on windowing, mention matching, and meta. The final sentence is dense with meta fields but every sentence carries information; no obvious filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by describing returned fields (author, board, resolved task name/column/url, verbatim comment text) and the contents of `meta`. Nothing an agent needs to call the tool correctly appears to be missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage the baseline is 3, but the description adds semantics not in the schema: it explains that `person.textSearched` reveals which names were matched and that `text` is for handles/exact phrases. This meaningfully augments the parameter documentation rather than repeating it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (searches/returns) and resource (comments across configured KanbanFlow boards), plus ordering (newest first) and resolution (author, board, task name/column/url). It is clearly distinguishable from siblings like list_tasks, search_tasks, and get_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent between `person` (mention search) and `text` (handle or exact phrase), and explains the activity-log mechanism that constrains the window. It stops short of naming sibling alternatives (e.g. when to use search_tasks instead), so it is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the tasks of one person across every configured KanbanFlow board (or the boards you choose), optionally only in some columns. By default the person is the configured user ("me"). Returns how the person was matched on each board, the tasks with board, column, swimlane, color, labels and people resolved to names, counts per board and column, and a meta block that reports boards where the person is not a member, filters that matched nothing and columns that were only partially loaded. The server does not rank or classify tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum tasks returned (default 50, max 500). Counts always cover every match. | |
| boards | No | Board ids or exact names to search (see list_boards). Default: every configured board. | |
| detail | No | "summary" (default) trims descriptions. "full" adds the complete description and the raw API object. | |
| person | No | Whose tasks: user id, email, full name or part of the name. Omit it (or use "me") for the configured user (KANBANFLOW_USER). A task matches when the person is its responsible user or a collaborator. | |
| columns | No | Column ids or exact names (case-insensitive), on any of the boards. Default: every column. Limited columns listed here (usually "done") are loaded completely. | |
| loadAllPages | No | Load every limited column completely, not only those in `columns` (slow on big boards). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (read-only, idempotent, open-world), and the description goes well beyond that: it details the return payload, a `meta` block that flags boards where the person is not a member, filters that matched nothing and partially loaded columns, and warns that the server does not rank or classify tasks. These are genuine behavioral traits not visible in the annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences that front-load the core scope and then the return shape. Every sentence carries information, though the long middle sentence listing resolved fields is slightly overloaded and could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so: it names the fields (board, column, swimlane, color, labels, people resolved to names), the per-board/column counts, the `meta` caveat block, and the non-ranked ordering. An agent has everything needed to interpret results and pick parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter thoroughly, including the `person` matching rule and the `limit` default/max. The description largely restates those meanings (default person = configured user) without adding new syntax or edge-case semantics, matching the baseline for a fully documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Lists the tasks') plus its scope: one person, every configured KanbanFlow board, optionally limited to columns. The agent can picture the output and the scope precisely. It does not explicitly name or distinguish itself from search_tasks, but the person-centric scope is clear enough to stand apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides useful defaults ('By default the person is the configured user ("me")') and hints at when the columns/loadAllPages options matter, but never says when to reach for this tool instead of search_tasks or get_task. Usage is implied rather than routed explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the time entries of KanbanFlow boards: every tracked interval with who tracked it, when it started and ended, how long it lasted and on which task. This is the only tool that breaks time down by day and by person; timeSpentHours in the other tools is the accumulated total of a task. Entries are found through the board activity log (totalSecondsSpent changes) unless you pass taskIds, and then read task by task. Totals are sums of entry durations, reported per person/board and per UTC day; two people working on the same task at the same time add up twice, so they are not elapsed time. meta reports the window, whether the activity log was read completely, entries that fell outside the window or have no end, and every API request made. The server does not interpret the board.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the window, ISO 8601 UTC (default: now). | |
| from | No | Start of the window, ISO 8601 UTC (default: 2 days before "to", which covers a local "today" in any time zone). The server does not decide what "today" or "this week" is: pass the window the user means, in their time zone. An entry is included when its start falls inside the window. | |
| limit | No | Maximum entries returned, newest first (default 100, max 500). Totals always cover every match. | |
| boards | No | Board ids or exact names to search (see list_boards). Default: every configured board. | |
| person | No | Only entries tracked by this person (user id, email, full name or part of the name). Use "me" for the configured user. Entries are attributed by the `userId` KanbanFlow records on each entry, which may be an integration id that is not a board member (then it is returned without a name). Omit it for everybody. | |
| taskIds | No | Read only these tasks (ids from list_tasks, search_tasks or get_task) instead of scanning the activity log for the window. Cheaper and exact when you already know the tasks; also the way to reach entries older than the activity log keeps. | |
| maxTasks | No | Maximum tasks whose time entries are read (default 50, max 100), most recently changed first. Each task costs one API request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly/idempotent/non-destructive), and the description adds genuinely non-obvious behavior: the double-counting rule ('two people working on the same task at the same time add up twice, so they are not elapsed time'), what `meta` reports (window, log completeness, entries with no end, every API request), and that the server does not interpret the board.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the return semantics and the sibling differentiation before the retrieval mechanics and `meta` caveats. Dense but nearly every clause carries load; the `meta` enumeration is the one segment that could be tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-param, no-output-schema, open-world tool, the description supplies the retrieval strategy, aggregation semantics, window semantics, and return-shape caveats an agent needs to call it correctly. Nothing material is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds operational meaning beyond the schema: the inclusion rule ('An entry is included when its start falls inside the window'), the cost model for `maxTasks` ('Each task costs one API request'), and why `taskIds` exists. It stops short of adding anything to `limit`/`boards` beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the time entries of KanbanFlow boards') and enumerates the payload fields (who tracked it, start/end, duration, task). It explicitly distinguishes itself from siblings by noting it is 'the only tool that breaks time down by day and by person' while `timeSpentHours` elsewhere is a task total.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the decision rule for the main fork: entries come from the board activity log unless `taskIds` is passed, and `taskIds` is recommended when the tasks are known because it is 'cheaper and exact' and reaches history older than the activity log. It also states when to omit `person` ('Omit it for everybody') and what the default window covers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finds tasks whose text contains a query, across every configured KanbanFlow board and column (or the boards and columns you choose). The query is split into words and, by default, all of them must appear somewhere in the fields you pick (fields, default name and description; labels, custom field values and subtask names are available too). Each task says in matchedFields which fields contained part of the query. KanbanFlow has no search endpoint, so tasks are loaded and filtered here: the counts cover only what was loaded, and meta reports failed boards and columns that came partially loaded (typically "done") with how to load them completely. Read-only. To search comments or mentions, use list_comments instead.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum tasks returned (default 50, max 500). Counts always cover every match. | |
| query | Yes | Text to find in the tasks, case-insensitive and as a substring. It is split into words; by default every word has to appear somewhere in the searched fields (AND). | |
| boards | No | Board ids or exact names to search (see list_boards). Default: every configured board. | |
| detail | No | "summary" (default) trims descriptions. "full" adds the complete description and the raw API object. | |
| fields | No | Where to look (default ["name", "description"]). "labels" searches the label names, "customFields" the custom field values (names are not in the API) and "subTasks" the subtask names. | |
| person | No | Only tasks of this person (responsible user or any collaborator): id, email, full name or part of the name. "me" uses the configured user. Default: everybody. | |
| columns | No | Column ids or exact names (case-insensitive). Default: every column. Limited columns listed here (usually "done") are loaded completely. | |
| loadAllPages | No | Load every limited column completely (slow on big boards). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld annotations by disclosing that KanbanFlow has no search endpoint, that work is client-side, that counts only cover loaded data, and that meta reports failed boards and partially loaded columns. It also notes read-only status and the matchedFields return hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: purpose, then matching semantics, then the local-filtering caveat, then the sibling pointer. Every sentence carries information, though the long middle sentences about loading behavior take effort to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining matchedFields and meta, and it covers the limiting/loading trade-offs of an 8-parameter tool. Nothing essential to selecting or invoking it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: query words are AND-combined by default, labels/customFields/subTasks map to specific values, and limited columns listed are loaded completely. It does not restate every parameter, but it clarifies the ambiguous ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Finds tasks whose text contains a query") plus scope (all configured boards/columns or chosen ones). It also differentiates from the sibling list_comments by naming it and the case it covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes to the alternative: "To search comments or mentions, use list_comments instead." Default behavior for boards, columns, fields and person is spelled out, so an agent knows when this tool applies and when it does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0get_tasklist_boardslist_commentslist_taskslist_time_entriessearch_tasksScored across 6 tools
Each tool has a clearly distinct selection criterion or return type: boards, person-based tasks, single task detail, comment search, time entries, and text-based task search. The descriptions explicitly distinguish list_tasks from search_tasks and list_comments, and get_task is the only id-based lookup. No two tools appear to do the same thing.
All tool names follow a consistent snake_case verb_noun pattern: list_*, get_*, and search_*. The conventions are predictable and readable throughout. There are no mixed styles or vague verbs.
Six tools is well within the ideal 3-15 range for this domain. Each tool covers a distinct retrieval or search need for KanbanFlow data. No tool feels redundant or unnecessary.
The read/query surface is thorough: boards, tasks, task details, comments, time entries, and search are all covered. However, there are no create, update, delete, comment-posting, or time-logging tools, which are notable missing lifecycle operations for a KanbanFlow integration. Agents would be unable to modify boards, tasks, or comments through this server.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Remote MCP for Kanban AI boards—manage projects, tasks, and comments from AI tools.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
