MCP tools

The 38 tools your agent gets when it connects — lean payloads, batch writes and safe retries included.

The MCP endpoint at /mcp exposes one tool per relevant operation — projects, fields, views, automations, cards, comments, search. This page lists every tool with its parameters, generated from the server at build time so it cannot drift.

Lean payloads

MCP responses are designed so agents don’t burn tokens reading boards:

  • Summary by default. get_board/list_cards return each card summarized ({ id, number, key, title, status }). Pass summary: false for the full payload, fields: [fieldId…] to project specific fields, or includeDescription: true when you need the text. For a single card, prefer get_card.
  • Lean writes. create_card/update_card/move_card/archive_card/add_comment also return the summary by default; summary: false brings the full payload.
  • Pagination. limit is an alias of pageSize, and offset skips items (overriding the page offset). Numeric fields accept strings ("10" → 10), so outdated client schemas keep working. Unknown arguments fail with an error instead of being silently ignored.
  • Batch. batch runs up to 50 writes in a single call (move_card, update_card, add_comment, archive_card, unarchive_card, delete_card). It is not a single transaction: by default it stops at the first error and reports per item (applied/failed with index and reason); continueOnError keeps going. Send idempotencyKey and the response is stored for 24 hours, so a retry does not duplicate effects. Batch does not create cards.

All tools

The table below is the live catalogue: tool, what it does, and its parameters (name, type, required).

38 tools, generated from the server at build time (npm run docs:mcp).

ToolDescriptionParams
add_commentAdds a comment to a card. Accepts `author` (or the `actor` alias) and a structured `role`, recorded in the activity trail.
8 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • body string · required
  • summary boolean — Returns {ok, id, cardId} instead of the full comment. Default: true.
  • author string — Who wrote it (default: mcp-agent). Shows up in the history.
  • actor string — Alias of `author` (consistency with the other tools).
  • role string — Structured role, e.g. "Scrum Master". Recorded in the Activity.
add_field_optionAdds an option to a SINGLE_SELECT/MULTI_SELECT/USER field (e.g. a new Status column, or a new label).
3 params
  • fieldId string · required
  • name string · required
  • color string
archive_cardArchives a card.
5 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • summary boolean — Returns the card summary. Default: true.
  • actor string — Who is performing this action (defaults to the API key name). Shows up in the card activity trail.
batchRuns a list of writes in a single call: move_card, update_card, add_comment, archive_card, unarchive_card, delete_card. NOT a single transaction: by default it stops at the first error and reports per item (index + reason); use continueOnError to keep going. Each op accepts cardId OR projectId+number. Send idempotencyKey so an agent retry does not duplicate effects. Does not create cards.
4 params
  • ops array · required
  • continueOnError boolean — Keeps going after an error instead of stopping. Default: false.
  • idempotencyKey string — Key for safe retries (response stored for 24h).
  • actor string — Who is performing this action (defaults to the API key name). Shows up in the card activity trail.
create_automationCreates an automation (trigger -> action), executed synchronously in a single pass (an automation never triggers another). Triggers: card_created, field_changed (fieldId+toOptionId), pr_merged (fired by the events endpoint when a PR is merged). Actions: set_field_value (fieldId + optionId or value), archive_card.
5 params
  • projectId string · required
  • name string · required
  • enabled boolean
  • trigger object · required
  • action object · required
create_cardCreates a card on a project. If statusOptionId is not given, the card goes to the first Status column. `fields` accepts values by fieldId (text/number/date as the raw value, single-select as an optionId, multi-select/user as an array of optionIds). USER fields accept principal refs (`user:<id>` / `key:<id>`, see `list_assignees`) or existing option ids.
7 params
  • projectId string · required
  • title string · required
  • description string
  • statusOptionId string
  • fields object
  • summary boolean — Returns the card summary (id, number, key, title, status) instead of the full payload. Default: true.
  • actor string — Who is performing this action (defaults to the API key name). Shows up in the card activity trail.
create_fieldCreates a custom field on the project. Types: TEXT, NUMBER, DATE, SINGLE_SELECT, MULTI_SELECT, USER. For SINGLE_SELECT/MULTI_SELECT/USER you can also send the initial options.
4 params
  • projectId string · required
  • name string · required
  • type "TEXT" | "NUMBER" | "DATE" | "SINGLE_SELECT" | "MULTI_SELECT" | "USER" · required
  • options array
create_projectCreates a new Kanban project. It already provisions the Status field using a template (default `agent-workflow`: Backlog / To Do / In Progress / Needs Human / In Review / Done plus Priority, Assignee and Labels; or `simple`: To Do / In Progress / Done) and the Board/Table views. The response includes the ids of the fields and of the Status options - store them, they are required to create and move cards.
4 params
  • name string · required
  • description string
  • key string — Short prefix to reference cards (e.g. "BAT" -> cards become "BAT-42"). Derived from the name when omitted.
  • template "agent-workflow" | "simple" — Project template; defaults to agent-workflow.
create_viewCreates a view. type BOARD must group by a SINGLE_SELECT field (groupByFieldId, usually Status). type TABLE is a filterable/sortable list.
7 params
  • projectId string · required
  • name string · required
  • type "BOARD" | "TABLE" · required
  • groupByFieldId string
  • filter array — AND conditions. operator: eq|ne|in|contains|is_empty|is_not_empty|before|after
  • sort object
  • visibleFieldIds array
delete_automationDeletes an automation.
1 param
  • automationId string · required
delete_cardPermanently deletes a card (irreversible - prefer archive_card when possible). Use for true duplicates/orphans.
3 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
delete_fieldDeletes a custom field (builtin fields like Status/Title cannot be removed).
1 param
  • fieldId string · required
delete_field_optionDeletes a field option (e.g. a board column). Cards that had this value are left without a value on that field.
1 param
  • optionId string · required
delete_projectDeletes a project and all its cards/fields/views/automations (irreversible).
1 param
  • projectId string · required
delete_viewDeletes a view.
1 param
  • viewId string · required
get_boardFetches a project's board in a single call: columns (Status field options) with the cards already grouped and ordered. By default each card comes summarized (id, number, title, status) to keep the payload small - use summary:false (or `fields`) only when you need the details, and get_card for a specific card.
8 params
  • projectId string · required
  • summary boolean — Summarized cards (id, number, title, status). Default: true. Ignored when `fields` is set.
  • fields array — Projection: only these fieldIds are included in each card's `fields`. Omit the description unless includeDescription=true.
  • includeDescription boolean — Includes each card's description. Default: false for summary/projection, true for the full format.
  • page integer
  • pageSize integer
  • limit integer — Alias of pageSize.
  • offset integer — How many items to skip (overrides the `page` offset).
get_cardCard detail, with the values of all fields. Accepts `cardId` OR `projectId` + `number` (e.g. BAT-107). Use summary:true or `fields` for a smaller response.
6 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • summary boolean — Summarized format (id, number, key, title, status). Default: false.
  • fields array — Projection: only these fieldIds are included in `fields`.
  • includeDescription boolean — Includes the description. Default: false for summary/projection, true for the full format.
get_card_activityAudit trail of a card (creation, field changes, moves, comments). Use `since` for "what changed since X".
5 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • since string — ISO datetime - only entries created after that.
  • limit integer
get_projectProject detail: fields, options and views.
1 param
  • projectId string · required
get_project_activityActivity across all cards of a project, newest first (creation, field changes, moves, comments). Use `since` for "what changed since X".
4 params
  • projectId string · required
  • since string — ISO datetime - only entries created after that.
  • limit integer
  • offset integer
get_view_itemsResolves any view by id: for BOARD returns grouped/ordered columns, for TABLE returns filtered/ordered/paginated rows. Use get_board when you only need the project's default board.
10 params
  • viewId string · required
  • archived boolean
  • q string
  • page integer
  • pageSize integer
  • limit integer — Alias of pageSize.
  • offset integer — How many items to skip (overrides the `page` offset).
  • summary boolean — Summarized cards (id, number, key, title, status) instead of the full payload. Default: false. Ignored when `fields` is set.
  • fields array — Projection: only these fieldIds are included in each card's `fields`. Omit the description unless includeDescription=true.
  • includeDescription boolean — Includes each card's description. Default: false for summary/projection, true for the full format.
list_assigneesLists the people (users) and agents (API keys) that can be assigned to USER fields, with the `ref` to use as the value (e.g. `user:abc`, `key:xyz`).none
list_automationsLists a project's automations.
1 param
  • projectId string · required
list_cardsLists/filters a project's cards (flat list, not grouped - use get_board for the column view). By default cards come summarized (id, number, key, title, status) to keep the payload small - use summary:false or `fields` when you need details. To find a card by number (BAT-107), use `number`.
16 params
  • projectId string · required
  • status string — Filters by column: accepts the Status option id OR name (e.g. "Backlog").
  • statusOptionId string — Same as `status`, but by id only (compatibility).
  • number integer — Exact card number within the project (BAT-107 -> 107).
  • q string — Text search on title/description.
  • filter array — Server-side per-field filters (AND), same operators as views. `fieldId` accepts the field id OR name; on select fields `value` accepts the optionId OR the option name. E.g. [{fieldId:"Labels", operator:"eq", value:"bug"}].
  • sort "position" | "updatedAt" — Sort order. Default: position (board order); updatedAt = newest first.
  • archived boolean
  • updatedSince string — ISO datetime - only cards updated after that.
  • page integer
  • pageSize integer
  • limit integer — Alias of pageSize.
  • offset integer — How many items to skip (overrides the `page` offset).
  • summary boolean — Summarized cards (id, number, key, title, status). Default: true. Ignored when `fields` is set.
  • fields array — Projection: only these fieldIds are included in each card's `fields`. Omit the description unless includeDescription=true.
  • includeDescription boolean — Includes each card's description. Default: false for summary/projection, true for the full format.
list_commentsLists a card's comments (paginated). Use `since` for "what changed since X" without re-reading the history.
6 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • since string — ISO datetime - only comments created after that.
  • page integer
  • pageSize integer
list_fieldsLists a project's fields (data columns) with their options.
1 param
  • projectId string · required
list_projectsLists the projects (boards).
1 param
  • archived boolean — Include archived projects (default: false).
list_viewsLists a project's views (Board/Table).
1 param
  • projectId string · required
move_cardMoves a card to another column (a Status field option). Without afterCardId/beforeCardId/position the card goes to the end of the target column.
9 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • statusOptionId string · required
  • afterCardId string — Positions the card right after this one.
  • beforeCardId string — Positions the card right before this one.
  • position number — Explicit numeric position (advanced).
  • summary boolean — Returns the card summary instead of the full payload. Default: true.
  • actor string — Who is performing this action (defaults to the API key name). Shows up in the card activity trail.
search_cardsFull-text search over card titles/descriptions and comment bodies (prefix match, any language). Returns short snippets; use get_card for details.
3 params
  • q string · required
  • projectId string
  • limit integer
unarchive_cardUnarchives a card.
5 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • summary boolean — Returns the card summary. Default: true.
  • actor string — Who is performing this action (defaults to the API key name). Shows up in the card activity trail.
update_automationUpdates an automation's name, enabled flag, trigger or action.
5 params
  • automationId string · required
  • name string
  • enabled boolean
  • trigger object
  • action object
update_cardUpdates a card's title/description/fields. Moving columns is also possible by passing the Status field id inside `fields`, but prefer the move_card tool - it also handles the position within the column. USER fields accept principal refs (`user:<id>` / `key:<id>`, see `list_assignees`) or existing option ids.
8 params
  • cardId string — Card id (cuid). Alternative to projectId+number.
  • projectId string — With `number`, locates the card by project number.
  • number integer — Card number within the project (BAT-107 -> 107). Requires projectId.
  • title string
  • description string | null
  • fields object
  • summary boolean — Returns the card summary instead of the full payload. Default: true.
  • actor string — Who is performing this action (defaults to the API key name). Shows up in the card activity trail.
update_fieldRenames or reorders a field.
3 params
  • fieldId string · required
  • name string
  • order integer
update_field_optionRenames, recolors or reorders a field option.
4 params
  • optionId string · required
  • name string
  • color string | null
  • order integer
update_projectRenames, updates the description of, or archives/unarchives a project.
4 params
  • projectId string · required
  • name string
  • description string | null
  • archived boolean
update_viewUpdates a view's name, grouping, filter, sorting or visible columns.
6 params
  • viewId string · required
  • name string
  • groupByFieldId string | null
  • filter array | null
  • sort object | null
  • visibleFieldIds array | null
whoamiReturns the identity behind the current API key: its name (used as the default actor) and id.none