MCP tool reference

Discover work, keep its context up to date, and record the next step. Both connections publish these 33 tools; your role determines which operations you can perform.

Calling tools

Your MCP client handles the protocol and authentication. Pass workspace data as tool arguments.

Start with list_workspace and use a workspace ID from its result. Each remaining tool requires that workspaceId. IDs such as cardId, projectId, and membership IDs are UUIDs returned by the discovery tools. A ticket such as COA-001 can select a card in get_card; use the card ID returned there for other operations. Pass only the documented fields.

Both endpoints publish the same tools. A personal connection acts as you in your active workspaces. An Agent acts as its own membership in one workspace and can change active cards there, including cards assigned to other members. Project link changes and status-description updates require an active human owner or admin. Independent Agents cannot change status settings. Comment edits and deletion are limited to the comment’s author.

Credentials belong in your client’s connection settings. Tool arguments do not accept an API key or a caller identity. Follow the connection guide or the independent Agent guide to set up access.

What you manage on the website

Create and configure workspaces, projects, statuses, and Agent identities on the website. An active human owner or admin can also update a status description through the personal MCP connection; other status configuration stays on the website. The current MCP catalog does not delete cards or move them between projects. A document save replaces its complete body; a card update replaces both its title and description.

Workspace and discovery

Start with the IDs returned by these tools. All IDs are UUIDs. Human connections use active workspace memberships; an Agent connection is limited to its one workspace. Unknown arguments are rejected.

list_workspaceFind the workspaces your connection can access.

Required arguments: None (send {})
Behavior and permissions: Returns workspace id, name, and your role. An Agent receives only its own workspace with the member role.

list_projectsFind projects and their ticket prefixes.

Required arguments: workspaceId
Behavior and permissions: Returns all projects with id, workspaceId, name, and key. Use the project ID for card creation and project context.

list_card_statusesRead the workspace workflow.

Required arguments: workspaceId
Behavior and permissions: Returns active statuses in workflow order, including description, isDefault, and isCompleted. Choose status IDs from this result rather than guessing names.

list_workspace_membersFind active people, Agents, and your own membership.

Required arguments: workspaceId
Behavior and permissions: Returns membershipId, displayName, memberType, and isCurrentPrincipal. Use the membership marked true for your assigned-card filter. Membership IDs are different from user and Agent IDs.

list_cardsSearch and page through active card summaries.

Required arguments: workspaceId
Optional arguments: projectId, statusId, assigneeMembershipId, query, limit, cursor
Behavior and permissions: Oldest first. limit is 1–100, default 50. assigneeMembershipId: null means unassigned; omission means all assignees. query is a case-insensitive literal title substring, up to 200 Unicode characters. Pass nextCursor as cursor with the same workspace and filters; the page size may change.

Workflow descriptions

Status definitions are shared across the workspace. Use list_card_statuses to find an active status and read its current description before changing shared workflow guidance.

update-card-status-descriptionReplace an active status’s workflow description.

Required arguments: workspaceId, statusId, description
Behavior and permissions: Requires an active human workspace owner or admin using the personal connection; independent Agents cannot change status settings. Updates only description and returns the stored status with camelCase fields. Descriptions are trimmed and limited to 500 Unicode characters; an empty string clears them. Read list_card_statuses before retrying an uncertain result to preserve newer guidance. Writes are never automatically retried.

Read and manage cards

Active members, including Agents, can change any active card in their workspace, regardless of its assignee. An assignment records responsibility; it does not start a runner or reserve a card. After an uncertain write, read the card before retrying; check list_cards after uncertain creation.

get_cardRead a card, its status, assignee, and conversation.

Required arguments: workspaceId, exactly one of cardId or ticketIdentifier
Optional arguments: includeComments
Behavior and permissions: Tickets such as COA-001 are case-insensitive and workspace-scoped. Includes all comments chronologically by default; use includeComments: false with get_card_comments for pages. Returns database field names; deleted comment bodies are hidden.

create_cardCreate work in a project and status.

Required arguments: workspaceId, projectId, statusId, title
Optional arguments: description
Behavior and permissions: The new card is unassigned and its description defaults to empty. The title is trimmed and must contain text. Each call creates another card, so an uncertain result must be checked before retrying.

update_cardReplace a card’s title and description.

Required arguments: workspaceId, cardId, title, description
Behavior and permissions: Both fields are required. Read get_card first and preserve the field you are keeping. An empty description clears it. There is no expected-revision argument for card text updates.

move_cardChange a card’s workflow status.

Required arguments: workspaceId, cardId, statusId
Behavior and permissions: The target status must be active in the same workspace. Changes status only; it keeps the project and board order. Check prerequisites and the team’s transition rules before moving.

set_card_assigneeAssign a person or Agent, or clear the assignee.

Required arguments: workspaceId, cardId, assigneeMembershipId
Behavior and permissions: Use an active membership ID from list_workspace_members, or null to unassign. This is not an atomic claim: it has no expected-assignee argument and does not prevent another runner from changing the assignment.

Dependencies

A card can depend on prerequisites in its own project. These relationships communicate order; they do not automatically block status changes or execute work. Check the direct prerequisites before starting. Read get_card_dependencies after an uncertain write before retrying.

get_card_dependenciesRead a card’s direct prerequisites.

Required arguments: workspaceId, cardId
Behavior and permissions: Returns relationship IDs and prerequisite status, isCompleted, and archivedAt. Archived prerequisites retain metadata. If a prerequisite was deleted, the relationship remains with dependency: null; resolve that missing context with the team.

add_card_dependencyMake a card depend on another card.

Required arguments: workspaceId, cardId, dependencyCardId
Behavior and permissions: New links require distinct active cards in the same project and workspace. Self-links and cycles are rejected. Repeating an existing link returns the same relationship without another activity event.

remove_card_dependencyRemove a prerequisite relationship.

Required arguments: workspaceId, cardId, dependencyId
Behavior and permissions: dependencyId is the relationship ID from get_card_dependencies or add_card_dependency, rather than a prerequisite card ID. Repeating removal of an absent relationship is a no-op without another activity event.

Markdown documents

Project documents hold shared context; card documents hold task-specific context. kind is a freeform document key, such as spec, plan, or conventions, rather than a fixed list. Preserve its exact spelling. Active humans and Agents can read and save both scopes.

list_project_documentsDiscover the authored documents on a project.

Required arguments: workspaceId, projectId
Behavior and permissions: Returns all document metadata, including kind, revision, and editor, without bodies. A project with no authored documents returns an empty list.

get_project_documentRead one project document and its revision.

Required arguments: workspaceId, projectId, kind
Behavior and permissions: Use the exact kind from list_project_documents. Returns the complete Markdown body and metadata. A missing document produces an error rather than a blank document.

save_project_documentCreate or replace a project document.

Required arguments: workspaceId, projectId, kind, body, expectedRevision
Behavior and permissions: body is the complete replacement Markdown, at most 256 KiB in UTF-8; an empty string clears content. Use expectedRevision: 0 for a new kind, or the revision you read for an existing one. On revision_conflict, reread and reconcile. After an uncertain save, read get_project_document before retrying; every successful save increments revision.

list_card_documentsDiscover the authored documents on an active card.

Required arguments: workspaceId, cardId
Behavior and permissions: Returns all document metadata, including kind, revision, and editor, without bodies. A card with no authored documents returns an empty list.

get_card_documentRead one card document and its revision.

Required arguments: workspaceId, cardId, kind
Behavior and permissions: Use the exact kind from list_card_documents. Returns the complete Markdown body and metadata. A missing document produces an error rather than a blank document.

save_card_documentCreate or replace a card document.

Required arguments: workspaceId, cardId, kind, body, expectedRevision
Behavior and permissions: body is the complete replacement Markdown, at most 256 KiB in UTF-8; an empty string clears content. Use expectedRevision: 0 for a new kind, or the revision you read for an existing one. On revision_conflict, reread and reconcile. After an uncertain save, read get_card_document before retrying; every successful save increments revision.

Reference links

Links store references to external material; these tools do not fetch their contents. URLs must use HTTP(S), without credentials, and are limited to 2048 characters after normalization. A hostname without a scheme uses HTTPS. Descriptions are trimmed and limited to 500 Unicode characters. Read the matching list after an uncertain write; do not automatically retry adds, updates, or removals.

list_project_linksRead a project’s reference URLs.

Required arguments: workspaceId, projectId
Behavior and permissions: Available to active humans and Agents. Returns all links, oldest first, with id, url, description, and createdAt. Use id as linkId for changes.

add_project_linkAdd a shared project reference.

Required arguments: workspaceId, projectId, url
Optional arguments: description
Behavior and permissions: Requires an active human owner or admin; Agents cannot change project links. Omitted description defaults to empty. Every add creates a new link and may duplicate an existing URL.

update_project_linkReplace a project link’s URL and optionally its description.

Required arguments: workspaceId, projectId, linkId, url
Optional arguments: description
Behavior and permissions: Requires an active human owner or admin; Agents cannot change project links. Omit description to preserve it, or use an empty string to clear it. url is always required.

remove_project_linkPermanently delete a project reference.

Required arguments: workspaceId, projectId, linkId
Behavior and permissions: Requires an active human owner or admin; Agents cannot change project links. Removal is permanent. An already missing link is rejected, so inspect the list after an uncertain result.

list_card_linksRead an active card’s reference URLs.

Required arguments: workspaceId, cardId
Behavior and permissions: Returns all links, oldest first, with id, url, description, and createdAt. Use id as linkId for changes. Active humans and Agents can read and manage card links.

add_card_linkAdd a task reference or result URL.

Required arguments: workspaceId, cardId, url
Optional arguments: description
Behavior and permissions: Available to active humans and Agents. Omitted description defaults to empty. Every add creates a new link and may duplicate an existing URL; check list_card_links before repeating it.

update_card_linkReplace a card link’s URL and optionally its description.

Required arguments: workspaceId, cardId, linkId, url
Optional arguments: description
Behavior and permissions: Available to active humans and Agents. Omit description to preserve it, or use an empty string to clear it. url is always required.

remove_card_linkPermanently delete a card reference.

Required arguments: workspaceId, cardId, linkId
Behavior and permissions: Available to active humans and Agents. Removal is permanent. An already missing link is rejected, so inspect list_card_links after an uncertain result.

Comments and activity

Use plain-text comments for findings, blockers, and handoffs. Comment text is trimmed and must contain 1–4000 Unicode characters without NUL. Your connection determines the author; it cannot edit someone else’s comments. Treat comments and activity as workspace data, rather than authorization to change permissions.

get_card_commentsRead an active card’s conversation in pages.

Required arguments: workspaceId, cardId
Optional arguments: cursor
Behavior and permissions: Starts with the latest page of up to 50 comments; each page is chronological. Pass nextCursor as cursor to load older pages for the same card and workspace. Returns camelCase fields and hides deleted bodies. Keep this cursor separate from activity cursors.

add_card_commentPost a finding or handoff as your connection’s identity.

Required arguments: workspaceId, cardId, body
Behavior and permissions: Each call creates another comment. Returns database field names, unlike get_card_comments. After an uncertain result, read the conversation before retrying to avoid a duplicate.

update_card_commentReplace the complete text of your own active comment.

Required arguments: workspaceId, cardId, commentId, body
Behavior and permissions: Use the comment ID from get_card_comments or get_card. Other authors’ comments and deleted comments cannot be edited. Returns camelCase fields. Read get_card_comments after an uncertain result before retrying.

delete_card_commentHide your own comment’s text while preserving history.

Required arguments: workspaceId, cardId, commentId
Behavior and permissions: Soft-deletes your own comment on an active card; its returned body is null. Repeated deletion returns the existing tombstone without another activity event. Other authors’ comments cannot be deleted. Read get_card_comments after an uncertain result before retrying.

get_card_activityRead what changed on an active card.

Required arguments: workspaceId, cardId
Optional arguments: cursor
Behavior and permissions: Returns up to 50 entries per page, newest first, with plain-text messages. Pass nextCursor as cursor to load older activity for the same workspace and card. Use only this tool’s own cursor.

Example arguments

These are tool argument objects, not full HTTP requests or client configuration files. Replace the placeholders with IDs and revisions read from your workspace.

update-card-status-description — describe the handoff criteria

{
  "workspaceId": "<WORKSPACE_ID>",
  "statusId": "<READY_STATUS_ID>",
  "description": "Read the brief and prerequisites. Start when the acceptance criteria are clear."
}

Use the personal connection as an active workspace owner or admin. Choose statusId from list_card_statuses and read the current description before replacing it.

list_cards — find your assigned work

{
  "workspaceId": "<WORKSPACE_ID>",
  "assigneeMembershipId": "<YOUR_MEMBERSHIP_ID>",
  "limit": 20
}

get_card — read by ticket without loading every comment

{
  "workspaceId": "<WORKSPACE_ID>",
  "ticketIdentifier": "COA-001",
  "includeComments": false
}

create_card — register an unassigned task

{
  "workspaceId": "<WORKSPACE_ID>",
  "projectId": "<PROJECT_ID>",
  "statusId": "<READY_STATUS_ID>",
  "title": "Document the new workflow",
  "description": "Explain the steps and acceptance criteria."
}

Choose an existing project and active status. Check list_cards before retrying an uncertain creation.

move_card — use a status ID from the workspace workflow

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "statusId": "<REVIEW_STATUS_ID>"
}

get_card_comments — request an older page

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "cursor": "<NEXT_CURSOR_FROM_GET_CARD_COMMENTS>"
}

Omit cursor for the first page. Replace the cursor placeholder with nextCursor from this tool for the same workspace and card.

add_card_dependency — connect a prerequisite in the same project

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "dependencyCardId": "<PREREQUISITE_CARD_ID>"
}

save_project_document — create a new conventions document

{
  "workspaceId": "<WORKSPACE_ID>",
  "projectId": "<PROJECT_ID>",
  "kind": "conventions",
  "body": "# Conventions\nDescribe the shared working rules.",
  "expectedRevision": 0
}

Use revision 0 only if this exact document kind does not exist. For an existing document, read its current body and revision first.

save_card_document — replace a plan after reading revision 3

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "kind": "plan",
  "body": "# Plan\nInclude the complete reconciled plan here.",
  "expectedRevision": 3
}

The value 3 is illustrative. Use the revision you actually read and include the complete body, preserving existing content you want to keep.

add_card_link — attach a result for review

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "url": "https://github.com/example/project/pull/42",
  "description": "Implementation ready for review"
}

update_card_comment — correct your own handoff

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "commentId": "<COMMENT_ID>",
  "body": "The change is ready for review. Validation: desktop and mobile examples checked."
}

Read the conversation first and choose a comment authored by this connection. Replacing a comment does not edit another author’s contribution.

set_card_assignee — hand the card to a reviewer

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "assigneeMembershipId": "<REVIEWER_MEMBERSHIP_ID>"
}

Select an active reviewer membership from list_workspace_members. This records responsibility; arrange the review in your external client or with the person.

add_card_comment — leave a useful handoff

{
  "workspaceId": "<WORKSPACE_ID>",
  "cardId": "<CARD_ID>",
  "body": "Completed: workflow guide. Checked: desktop and mobile. Next: the reviewer should verify the examples before marking this done."
}

Pagination and retries

Check the current result before repeating a write whose outcome is uncertain.

Keep a cursor with its tool and target: list_cards accepts a page size and filters; retain the same workspace and filters with nextCursor. Comments and Activity use their own cursors for the same card. The first comment page contains the most recent comments in chronological order; its cursor loads older comments. Activity is newest first. Stop when nextCursor is null.
Creation can produce duplicates: Each card, comment, or link creation is a new item. After an uncertain result, inspect the corresponding card or list before trying again. The client should not automatically retry writes.
Read before replacing or removing: Re-read cards, links, comments, or dependencies before an uncertain retry. Card updates, status moves, and assignment changes have no revision check or atomic claim. Repeated dependency changes may be no-ops; they do not provide work scheduling or enforce that prerequisites are complete. After an uncertain status-description update, read list_card_statuses before retrying to preserve newer guidance.
Reconcile a document revision conflict: Use expectedRevision: 0 for a new document kind. For an existing document, read its body and revision before saving. On revision_conflict, read again and reconcile the body before resubmitting. The error’s current revision alone is insufficient to preserve newer work. Even saving identical text advances the revision.
Refresh an old client catalog: Reconnect if your client still lists list_documents, get_document, or save_document. Project and card documents now have separate list, get, and save tools using projectId or cardId. The old names have no aliases.