# Using bugboard from your project (MCP)

bugboard exposes an **MCP server** so an AI coding agent can read and write your
tasks directly — file bugs, list and update work, comment, and link tasks into
initiatives — without a hand-rolled REST integration.

For agents **without** a BugBoard account there is a separate, free server with
a few checks to run before filing work (duplicate check, bug report from a log,
spec to tickets, board converter, a shared task list): see
[the tools for agents page](https://bugboard.ai/tools/for-agents). It exposes none of the tools below.

## Connect

Per-client setup (Claude Code, Cursor, VS Code, Windsurf, Codex) is served as Markdown at
`https://bugboard.ai/mcp-server/<client>.md` (`claude-code`, `cursor`, `vscode`, `windsurf`, `codex`). For Claude Code, add the server to your repo's MCP config, `.mcp.json`:

```json
{
  "mcpServers": {
    "bugboard": {
      "type": "http",
      "url": "https://api.bugboard.ai/mcp/sse",
      "headers": { "Authorization": "Bearer ${BUGBOARD_MCP_TOKEN}" }
    }
  }
}
```

- **Token:** create one in the bugboard web app on the **MCP** page. It starts
  with `bb_` and is scoped to your user within one org. Keep it out of committed
  files — reference an env var (`${BUGBOARD_MCP_TOKEN}`) and set it in your shell
  or secrets manager.
  The full key is shown **once**, right after it is created. The server stores
  only a sha256 hash of it, so it can never be displayed again — if you lose it,
  use **Re-issue** on that key to mint a replacement. Re-issuing invalidates the
  old key immediately.
  The API is also an OAuth authorization server for this endpoint, which issues
  tokens of the same kind to an approved client: see MCP_OAUTH.md.
- **Transport:** `POST /mcp` is the Streamable HTTP endpoint: one JSON-RPC
  message per POST, answered with one JSON object, with no session id.
  `GET /mcp` and `DELETE /mcp` answer `405` (no server-to-client stream, no
  session to end), and a POST carrying an `Origin` header that is not an
  allowed web origin gets `403`. `initialize` answers the client's protocol
  version when it is one of `2025-11-25`, `2025-06-18`, `2025-03-26` or
  `2024-11-05`, and `2025-11-25` otherwise; an `MCP-Protocol-Version` header
  naming anything else gets `400`. The older two-channel transport stays: `GET
  /mcp/sse` opens the event stream and the client posts JSON-RPC to `/mcp/sse` or
  `/mcp/message` (the config above uses it). Every call
  is authenticated, authorized to the token's org/project, rate-limited, and
  audit-logged. A notification (a message without an `id`, such as
  `notifications/initialized`) gets `202 Accepted` with no body and nothing on
  the event stream, as JSON-RPC and MCP require.
- **Scopes:** a key can be narrowed below its owner at creation time,
  by passing either or both to `POST /api/v1/auth/token`:

  ```json
  { "name": "review agent",
    "scopes": ["project.read", "project.write"],
    "projectIds": [42] }
  ```

  Valid scopes are `project.read`, `project.write`, `project.manage`,
  `org.manage`, `org.roster.view`. Omitting a field means "unrestricted on that
  axis" — which is what every key issued before scopes existed carries, so
  existing keys keep working unchanged.

  Scopes only ever **subtract**. The effective permission of a call is
  `intersect(what the owner may do, what the key allows)`, so a key listing
  `org.manage` while its owner is a plain member still cannot manage the org.
  A key scoped to specific projects cannot see the others at all — they are
  absent from `list_projects` and `search_tasks`, not merely refused on open.

  The same holds for sub-issues: with a project-scoped key, `create_task` and
  `create_tasks` (`parent`) and `set_task_parent` (`parent_task_id`) refuse a
  parent that is not in one of the key's projects, and `set_task_parent` also
  refuses a child that is not. A parent in another project and a parent that does
  not exist get the same error (`parent task not found in this API token's
  projects`), so the answer does not reveal which task ids exist elsewhere. A key
  without `projectIds` is unaffected.

  `update_tasks` and `bulk_update_tasks` refuse the whole batch, changing
  nothing, when any of its tasks or the `project_id` it moves them to is outside
  the key's projects, or on a board the owner cannot edit. `resources/read` is
  narrowed exactly as tool calls are: it is a read, so it needs `project.read`,
  and it reaches only the key's projects.

  Tools are classified read vs write for `project.read` / `project.write`; a
  read-scoped key is refused at dispatch on anything that mutates.

  `tools/list` announces each tool's `title` and its `readOnlyHint` and
  `destructiveHint` annotations. A tool is read-only when the scope table above
  says so (plus `draft_task`, which returns a suggestion and saves nothing); a
  write is announced non-destructive only when it purely adds (create, comment,
  link, tag, vote, log time) and destructive otherwise, including any tool not yet
  classified (`apps/api/internal/mcp/annotations.go`).

## Tools

Use the unified **task** surface (a task's `type` is bug / feature / change):

| Group | Tools |
|---|---|
| Read | `list_projects`, `list_tasks`, `search_tasks`, `get_task`, `list_subtasks`, `list_comments` |
| Write | `create_task`, `create_tasks`, `update_task`, `update_tasks`, `comment_task`, `set_task_parent`, `change_task_type`, `draft_task` |
| Dedup | `check_duplicates` (call before filing; also searches the project's linked GitHub repo, see [Checking duplicates](#checking-duplicates)) |
| Initiatives | `create_initiative`, `list_initiatives`, `link_task_to_initiative`, `list_initiative_tasks` |
| Links | `link_tasks` / `unlink_tasks` / `list_task_links` (relations: blocks / relates_to / duplicate_of / chain) |
| Board columns (`list_project_columns` also for a project-scoped key; `set_project_columns` org owners and admins) | `list_project_columns`, `set_project_columns` |
| Tags & notifications | `list_project_tags`, `create_tag`, `add_tag_to_task`, `remove_tag_from_task`, `add_tag_to_tasks`, `remove_tag_from_tasks`, `list_my_notifications`, `mark_notifications_read` |
| Testing | `list_test_areas`, `add_test_areas`, `create_test_feature`, `record_test_result`, `update_test_feature`, `link_task_to_test_feature`, `list_test_features_for_task` |
| Time tracking | `log_time`, `start_timer`, `stop_timer`, `get_running_timer`, `list_time_entries`, `update_time_entry`, `delete_time_entry`, `get_task_time` |
| Brainstorm canvas | `list_canvas_cards`, `create_canvas_card`, `update_canvas_card`, `move_canvas_card`, `delete_canvas_card`, `vote_canvas_card`, `promote_canvas_card`, `comment_canvas_card`, `assign_canvas_card`, `add_tag_to_canvas_card` / `remove_tag_from_canvas_card`, `add_person_to_canvas_card` / `remove_person_from_canvas_card`, `link_task_to_canvas_card` / `unlink_task_from_canvas_card` |

`draft_task` sends the raw text to the AI provider, so it returns an error
(`AI is disabled for this organization`) when the org has switched AI off.

Legacy `*_bug` / `*_feature` tools still exist but are hidden from `tools/list`
unless `BUGBOARD_MCP_SHOW_LEGACY=1` — prefer the task tools.

Where the server is listed for installation (MCP registry, Claude connectors and plugin,
Cursor and VS Code buttons) is in `docs/MCP_LISTINGS.md` of the repository.

### Searching tasks

`search_tasks {query, types?, project_id?, limit?}` is the duplicate check to run
before filing. It matches `query` case-insensitively against title and
description (`%`/`_` in the query match themselves) over **every task type**
(`bug`, `feature`, `change`; test tasks are never returned), in one query across
all projects the caller can access.

- `types` — comma-separated subset of `bug`, `feature`, `change`; default all
  three. An unknown name is an error, not ignored.
- `project_id` — search only that project. A project the caller cannot access is
  refused with an error (it is not silently treated as empty).
- `limit` — default 10, max 50.

Hits are ranked across projects, not project by project: title matches first,
then most recently updated. Each hit reads
`N. change-7 (id=…, project_id=…): <title> · in <project>` followed by the first
100 characters of the description; the key prefix is `bug-`, `feat-` or
`change-`. When more tasks match than `limit`, the output ends with
`Results cut off at limit=N: more tasks match.` and the ways to see the rest
(narrow the query, pass `project_id`, raise `limit`). `No results found.` means
nothing matched.

### Checking duplicates

`check_duplicates {project_id, type, title}` is the check to call right before
`create_task` in one project. It returns the project's tasks of the same `type`
whose title or description contains `title` (case-insensitive, near-exact).

When the project is linked to a GitHub repository, it also reads that repo's
issues and returns the ones close to `title` next to the BugBoard tasks. Linked
means the project's repository preferences name a GitHub App repository of the
org (the project's defaults first, at most three repos), or, without those, the
project's own GitHub binding. The issues are read through the org's GitHub App
installation, the same one that opens pull requests; no other credential is
used, and a suspended installation is not called. Whoever can read the project
sees the titles and links of matching issues of its linked repos.

- Read: the 300 most recently updated open issues and up to 100 issues closed
  (updated) in the last 30 days; pull requests are left out. A repo's issues are
  kept in memory on the API replica for 5 minutes, a failed read for 1 minute;
  nothing is stored.
- Scored: the BugBoard tasks and the issues are scored against `title` together
  by the lexical scorer of the public duplicate check (`apps/api/internal/textsim`,
  TF-IDF cosine), so scores of both sources compare. GitHub issues below the
  related threshold (0.30) are left out, and at most five are returned. Every
  BugBoard task that matched is returned; one scoring below 0.30 is labelled
  `weak`.
- GitHub trouble never fails the tool: the call waits at most 4 seconds for
  GitHub (a slower read goes on in the background and fills the cache for the
  next call), and a rate limit keeps the whole installation off GitHub until
  GitHub's reset time. The repo's entry in `github` then carries `error`
  (`timeout`, `rate_limited`, `no_access`, `unavailable`) and the answer a
  `note`; the BugBoard part is complete either way. `no_access` usually means
  the GitHub App lacks the Issues read permission on that repo.

Without a linked repo the reply is `{count, duplicates:[{id, taskId, type,
title, status}]}`, unchanged. With one:

```json
{
  "count": 2,
  "duplicates": [
    {"source": "github", "repo": "acme/web", "number": 412,
     "title": "Checkout button does nothing on Safari", "state": "closed",
     "url": "https://github.com/acme/web/issues/412", "score": 0.71,
     "label": "likely_duplicate"},
    {"source": "bugboard", "id": 812, "taskId": 41, "type": "bug",
     "status": "pending", "title": "Checkout does nothing on Safari",
     "state": "open", "url": "https://bugboard.ai/projects/7/tasks/41",
     "score": 0.64, "label": "likely_duplicate"}
  ],
  "github": [{"repo": "acme/web", "compared": 214, "cachedAt": "2026-11-16T09:30:00Z"}],
  "thresholds": {"related": 0.3, "duplicate": 0.55}
}
```

`duplicates` is best first; `state` is `open` or `closed` (a BugBoard task in
Done is `closed`); `label` is `likely_duplicate` (score ≥ 0.55), `related`
(≥ 0.30) or `weak`. `github[].partial` is true when the repo has more open or
recently closed issues than were read. A likely duplicate is better answered
with `comment_task` on the BugBoard task, or by linking the GitHub issue, than
with a new task.

### Rate limit

Every call to `/mcp`, `/mcp/sse` and `/mcp/message` counts against a cap that is **per
API token**: **300 requests per 60 seconds** by default. `MCP_RATE_LIMIT` overrides
it (requests per minute; unset, non-numeric or ≤ 0 means 300). The window is
fixed, not sliding, and the key is the `Authorization` header, so every client
presenting one token shares one cap (a gateway that calls with one token for all
of a project's agents included). The cap counts HTTP requests, not tools: batch tools spend one request
for many rows.

A call over the cap gets `429` with a `Retry-After` header and a JSON-RPC error
whose message and `data` carry the same numbers, so an agent can wait instead of
guessing:

```json
{ "jsonrpc": "2.0", "id": null,
  "error": { "code": -32603,
             "message": "rate limited (per-token cap reached): 300 requests per 60 seconds, retry in 41 seconds",
             "data": { "limit": 300, "window_seconds": 60, "retry_after_seconds": 41 } } }
```

`retry_after_seconds` is the time until the current window resets. To tag many
tasks, use the bulk tag tools below rather than one `add_tag_to_task` per task:
110 tasks are 1 call, 1,100 are 6.

### When the token is rejected

The token is checked on **every** request, not once per connection: a call with a
key that was revoked, re-issued or has expired gets `401` at once, and the next
call with a good key is accepted with no server-side state to clear. A key is
valid for 90 days by default (1 to 365 at creation) and the server does not warn
before it runs out. **Re-issue** invalidates the old key immediately (see
[Connect](#connect)).

The `401` body says which case it is. The code is `INVALID_TOKEN` for both, so a
client that already handles it keeps working; `error.details.reason` and the
message tell them apart:

```json
{ "success": false,
  "error": { "code": "INVALID_TOKEN",
             "message": "API token expired at 2026-09-05T12:00:00Z; re-issue it on the MCP page",
             "details": { "reason": "expired", "expiredAt": "2026-09-05T12:00:00Z" } } }
```

```json
{ "success": false,
  "error": { "code": "INVALID_TOKEN",
             "message": "Invalid API token",
             "details": { "reason": "invalid" } } }
```

`expired` means re-issue the key on the **MCP** page. `invalid` means the server
does not accept this key: it was never issued here, was deleted or re-issued, its
owner is an agent, or it was copied wrongly; check the key and the endpoint
before minting another. A bearer that does not start with `bb_` gets `INVALID_TOKEN`
with the message `Invalid API token format`, and a missing or non-`Bearer` header gets
`UNAUTHORIZED`.

Whether a client picks up a new key without a restart is the client's behaviour,
not the server's. Claude Code reads `.mcp.json` when the session starts; after a
rejected key, the tools can stay gone even though the new key works at once with
curl. The way back inside the session is
the same endpoint over plain JSON-RPC, which needs no MCP connection:

```bash
curl -s https://api.bugboard.ai/mcp/message \
  -H "Authorization: Bearer $BUGBOARD_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_task","arguments":{"id":123}}}'
```

Without a `sessionId` on the URL the reply comes back in the response body (a
POST with `?sessionId=` is answered with `202` and the reply goes to the event
stream). Every tool is reachable this way.

### Reply shapes

Every reply stays in the calling agent's context, so the task tools return what
an agent acts on and nothing else.

- **People are `{id, email}`.** `createdBy` and `assignees` (on `get_task`,
  `list_tasks`, `list_my_tasks`, and in every write reply) never carry the user
  record: no avatar image, which is a base64 `data:` URL of several KB. No MCP
  reply contains image data.
- **Writes confirm.** `update_task`, `create_task` and `create_change` reply with
  a short object: `id`, `taskId`, `key` (`"bug-27"`, `"feat-3"`, `"change-3"`,
  what `update_task`'s `key` argument takes back), `type`, `projectId`, `title`,
  `status`, `priority`, `severity` (when set), `assignees` (the resulting set),
  `parentId` (when set), `pullRequestUrl` (when set), `updatedAt`, and on
  `update_task` `changed`, the
  arguments that call applied (`["status", "assignees"]`). Under 500 bytes for an
  ordinary title. To read the rest of the task, call `get_task`.
- **`update_tasks`** is all-or-nothing, so it replies `{"updated": <count>,
  "ids": [<global ids that passed validation>]}` and has no failure list: a batch
  that cannot be applied is refused whole with an error. When `set` names no
  field, nothing is written and `updated` is 0 while `ids` still lists the
  validated tasks. (`bulk_update_tasks` replies `updated` and `requested`.)
- **`get_task`** returns the task with its comments, sub-issues, tags and
  `key`. Sub-issues are summary rows (`id`, `taskId`, `key`, `type`, `title`,
  `status`, `priority`, ...); `full: true` returns them as whole tasks.
  `include_comments: false` leaves the comment bodies out when only the fields are
  needed; `commentCount` still says how many there are, and `list_comments`
  returns them alone. A task with no comments has `"comments": []`, so empty and
  left out can be told apart.
- **`list_tasks` and `search_tasks`** return short rows: `list_tasks` gives `id`,
  `taskId`, `key`, `type`, `title`, `status`, `priority`, `severity`, `projectId`,
  `assignees`, `pullRequestUrl` (when set), `createdByEmail`, `commentCount`,
  `attachmentCount`, `updatedAt`; `full: true` returns whole tasks (description and every other field). `search_tasks`
  returns one text line per hit. Page `list_tasks` with `limit` and `offset`.

### Task types

Tools that take a task by its global id work on every task type: bug, feature
and change. That holds for `add_tag_to_task`, `remove_tag_from_task`, the bulk tag
tools and `batch_add_comments` (a `task_ids` list may mix the three types).

`batch_add_comments {comments}` takes a JSON array of `{content, id}` objects,
at most 100 per call, where `id` is the task's global id. `bug_id` and
`feature_id` are still accepted as aliases for `id`; the task's type is read from
the task, not from which key was used. Items that fail (no id, unknown task, no
access) are listed in the reply without stopping the others.

### Bulk tags

`add_tag_to_tasks` and `remove_tag_from_tasks` take `{project_id, tag_id,
task_ids}`: one tag, many tasks of one project, at most **200** `task_ids` per
call (`MaxTagBatchSize`). Tasks are addressed by **global id**, the same `task_id`
`add_tag_to_task` takes (what `list_tasks` returns as `id`), not the per-project
number. Each call writes with a single SQL statement and is idempotent.

- **Result:** `add_tag_to_tasks` returns `{"tag_id", "added", "alreadyTagged"}`,
  `remove_tag_from_tasks` returns `{"tag_id", "removed", "notTagged"}`. A repeated
  id in `task_ids` counts once.
- **All or nothing:** the call is refused, with nothing written, when `task_ids`
  is empty or over 200, when any id is not a task of `project_id` (the error names
  them), or when the tag does not exist or belongs to another project.
- **Authorization** is `add_tag_to_task`'s: the token must allow `project.write`
  and the project, and the caller needs write access to the project.
- **Audit:** like every `tools/call`, a bulk tag call gets one MCP audit row
  (tool, arguments with all the ids, outcome). Neither the single nor the bulk tag
  tools write a task activity-log entry.

### Tag routes (HTTP)

The web client and the mobile apps attach tags with `POST` / `DELETE`
`/api/v1/bugs/:id/tags/:tagId` and `/api/v1/features/:id/tags/:tagId`. The two
prefixes are the same operation: `:id` is a task's global id and the task may be
a bug, a feature or a change through either. They run through the same code as
`add_tag_to_task` / `remove_tag_from_task`.

| Status | When |
|---|---|
| `204` | Attached or detached. Also when the task already has the tag (add) or never had it (remove): both are idempotent no-ops, as they were before the bulk tag tools. |
| `403` | The caller cannot write the tag's project, or the task is not a task of the tag's project. That covers a task of another project, a task of another org and a task id that does not exist: one answer for all three, so the response does not tell a caller which ids exist elsewhere. |
| `404` | The tag does not exist. |

Tags are created and renamed with `POST /api/v1/tags` and `PATCH /api/v1/tags/:id`.
A tag name is unique within its project, compared case-insensitively and after
trimming. Creating a tag with a name the project already has, or renaming a tag
onto another tag's name, answers `409` with code `CONFLICT` in the standard error
envelope and changes nothing.

### Assignees

A task can have **several** assignees. `create_task` / `update_task` /
`create_tasks` take `assignees` — a comma-separated list where each entry is
`"me"`, an email, or a user id (`"me, alice@example.com"`). An email or id must
belong to a member of the key's organization; any other is refused with the
same answer whether or not the account exists. On `update_task` it
**replaces** the whole set, so send everyone who should be on the task; an empty
string unassigns. `update_tasks` takes the same `assignees` key inside `set`
(and `assignee_ids` on the legacy `bulk_update_tasks` shape).

`assignee` / `assigned_to_id` still work as single-assignee spellings and lose
to `assignees` when both are sent. `list_tasks`'s `assignee` filter is
single-valued and means "this person is **among** the assignees" — passing
several addresses is an error rather than a silent truncation.

### Board columns

`list_project_columns {project_id}` and `set_project_columns {project_id,
columns, move?, landing_column?}` read and replace a project's board. The
replacing tool is the only one that changes a board's shape, and it is narrower
than the rest: the caller must be an org **owner or admin**, and a key must allow
`org.manage` (a key with no action list does) and must **not** be scoped to
projects. A project agent's key is scoped to its project, so `set_project_columns`
refuses it even when the user behind it is an admin; so it does an org member.

`list_project_columns` also answers a key **scoped to projects**, for the
projects in its scope and read-only: the project's own agents read their board's
columns with their own key. Such a key is held to the usual scoped read: the user
behind it must reach the project (an org owner or admin, or a project member) and
the key must allow `project.read` (a key with no action list does). A project
outside the key's scope is refused (`forbidden`), as for every scoped read. An
unscoped key keeps the rule above (`org.manage`); an org member without such a key
is refused. For an unscoped caller a project of another org reads as not found; for a
scoped key it is `forbidden`, like any project outside its scope.
`list_project_columns` is a read (`project.read`); `set_project_columns` needs
`project.write`.

`list_project_columns` replies `{"project_id", "landing_column",
"new_task_column", "columns": [{"key", "label", "type", "color", "position",
"task_count"}], "unplaced_task_counts"?}`, columns in board order. `type` is
always set: a column stored without one reads as the type its key implies.
`landing_column` is the key set for new tasks, `""` when the project has not set
one or the stored key is no longer a column; `new_task_column` is where a task
created without a status lands right now (the landing column, else the first
`triage` column by position, else the To Do column: `pending`, else the leftmost
`todo`-typed column). `unplaced_task_counts` appears
only when tasks hold a status no column has, as `{status: count}`.

Column types are `todo`, `backlog`, `triage`, `in_progress`, `blocked`, `test`,
`review`, `done`, `archive`. `backlog`, `triage` and `blocked` are not resolved
(a task in them is open).

`set_project_columns` **replaces** the whole set, so send every column the board
should keep:

- `columns` is an array of `{key, label, type, color?, position}`, in board
  order (columns are sorted by `position`, ties in array order, then renumbered
  0..n-1). It is checked by the rule the REST endpoint applies
  (`ValidateColumnsJSON`): keys are unique, `type` is a known column type, and at
  least one column has type `done`.
- `move` is an object `{old_key: new_key}`. A column you remove that still holds
  tasks is refused unless `move` names where its tasks go (the error names the
  column and how many tasks it holds); they move in the same transaction as the
  new set. A `move` whose key is not a current column or is a column you keep, or whose
  target is not in the new set, is refused too.
- `landing_column` is the key new tasks land in. Leave it out to keep the current
  setting; `""` clears it. A landing key, sent or kept, that is not a column of
  the new set is refused, unless `move` carries that column's tasks to a column of
  the new set: then the setting follows them. A set with more than one
  `triage` column must name its landing column (it cannot end up with none),
  because "the first triage column by position" would otherwise decide where new
  work goes.

It replies with the board as it now is, in the shape of `list_project_columns`,
plus `moved: {old_key: count}` when tasks moved. A refused call changes nothing,
and a malformed `columns`, `move` or `landing_column` is refused before the
service is asked. The tasks of a removed column are rewritten in one
statement per column, not through the task service: no `task.status_changed`
webhook fires and no task hook runs (a board edit can move thousands of tasks).
A move into a `done` column therefore does not do what `update_task` with
`status: "done"` does, such as closing linked test features.

### Pull request link

`update_task` takes `pull_request_url` and `update_tasks` takes it inside `set`:
the pull request that resolves the task, shown in the task's right panel. It must
be an `https` URL with a host, at most 500 characters and without whitespace;
`""` clears it. Anything else is refused with an error naming
`pull_request_url`, and a batch with a bad value changes nothing. A call that
leaves the field out keeps the link. `get_task` and `list_tasks` return it as
`pullRequestUrl`, and the key is absent on a task with no link.

### Brainstorm canvas

The **Brainstorm** view is a freeform, multiplayer board (a Miro-style canvas)
of sticky / idea / widget cards that can graduate into real tasks. An agent
can read and shape it directly:

- `list_canvas_cards {project_id}` — see the board and resolve card ids.
- `create_canvas_card {project_id, kind, text?, body?, html?, x?, y?}` —
  drop a card. `kind=sticky|idea` carry text; `kind=widget` carries a
  **self-contained HTML fragment** (inline styles/scripts only — the card
  renders it in a sandboxed iframe with no network access) so an agent can
  sketch a mockup, chart, or prototype straight onto the board.
- `update_canvas_card {card_id, text?, body?, html?, color?}` — rename,
  edit the markdown description, replace a widget's HTML (re-prompt a
  widget by passing new markup), or recolor.
- `move_canvas_card {card_id, x, y}` — reposition in board coordinates.
- `vote_canvas_card {card_id, delta?}` — upvote (or downvote) an idea.
- `add_tag_to_canvas_card` / `remove_tag_from_canvas_card {card_id, tag_id}`
  — apply project labels (ids from `list_project_tags`).
- `add_person_to_canvas_card` / `remove_person_from_canvas_card
  {card_id, user_id}` — manage watchers (ids from `list_org_members`).
- `unlink_task_from_canvas_card {card_id, task_id}` — undo a task link.
- `promote_canvas_card {card_id, task_type?}` — graduate a card into a
  bug/feature/change, link it back, and flip the card to a `task_ref`.
- `comment_canvas_card {card_id, body}` — discuss on a card; notifies
  everyone watching it (author, assignee, added people).
- `assign_canvas_card {card_id, assignee_id?}` — set/clear a card's owner
  (the assignee is notified). Omit `assignee_id` to unassign.
- `link_task_to_canvas_card {card_id, task_id}` — attach an existing task
  as related work (distinct from `promote`, which creates a new one).
- `delete_canvas_card {card_id}`.

Cards carry a description, an assignee, watchers, project tags, and linked
tasks — the same shape a task has — and all of it drives inbox
notifications, so an agent working a board keeps humans in the loop.

Every mutation fans out live over SSE (topic `canvas:<projectId>`), so a card
an agent creates **appears in real time** on any teammate's open board — the
agent is just another cursor on the canvas. The project's `brainstorm` feature
flag only controls the UI tab; the tools work regardless so an agent can seed a
board before a human turns the view on.

### Testing (manual test coverage)

bugboard's **Testing** view tracks which of an app's screens/features have been
**manually** tested — the click-through-it-yourself kind, distinct from
automated tests. A **test feature is a task** with `type="test"`: full title /
description / comments / activity / assignee / priority, opens the normal task
page, but is **hidden from every normal board/list/search** and shown only in the
Testing tab. **Test areas** are the board's columns; a feature's `area_id` is its
column. Each feature has a decaying **test status** (`untested` / `verified` /
`needs_review` / `failing`) separate from the task status, plus checks and a link
to the tasks that affect it. **Closing a linked task flips the feature to
`needs_review`** — so link the work you do to the features it touches. Because a
feature is a task, edit its title/description/priority/assignee with `update_task`
and discuss it with `comment_task` using the same feature id.

| Group | Tools |
|---|---|
| Read | `list_test_areas`, `list_test_features_for_task`, and the `bugboard://guide/testing` resource |
| Map | `add_test_areas` (bootstrap many at once from a repo's routes/screens), `create_test_area`, `create_test_feature`, `update_test_area`, `delete_test_area`, `delete_test_feature` |
| Test | `record_test_result` (`pass` / `fail` (files+links a bug) / `rereview`), `update_test_feature` (status / priority / assignee / checks) |
| Link | `link_task_to_test_feature`, `unlink_task_from_test_feature` |
| Discuss | `comment_test_feature` |

Recommended flow: `list_test_areas` to see the map → when you fix a bug or ship a
change, `link_task_to_test_feature` so the affected features auto-flag for
re-review on close → `record_test_result` when a human (or you) has verified.

### Time tracking

An agent can log, edit and inspect hours on tasks. Design: `docs/TIME_AND_COST.md`.

- `log_time {task_id, duration, date?, notes?, billable?}` — add an entry.
  `duration` is forgiving and parsed server-side: `90` (bare integer =
  **minutes**), `1.5` (bare decimal = **hours**), `1h30`, `1h 30m`, `1:30` and
  `30m` all mean ninety minutes. A minutes component of 60 or more in a two-part
  form (`1h70`) is rejected as a typo, as is anything over 24h — the per-entry
  cap. `date` is `YYYY-MM-DD` and defaults to today; `billable` defaults to true.
- `start_timer {task_id}` / `stop_timer {}` / `get_running_timer {}` — one
  running timer per person, enforced by the database. Starting a second timer is
  **refused** and the refusal names the task already being tracked; the API never
  auto-stops, because silently stopping a timer someone forgot about loses time
  they cannot recover. Call `stop_timer` first to switch.
- `list_time_entries {task_id? | project_id?, from?, to?, user?}` — at least one
  of `task_id` / `project_id` is required. `from` / `to` are `YYYY-MM-DD` and
  `to` is inclusive of that whole day. `user` accepts `"me"`, an email, or a user
  id. Returns `{count, totalTime, entries}`.
- `update_time_entry {id, duration?, notes?, billable?}` /
  `delete_time_entry {id}` — editing never re-rates an entry, so an invoice
  already sent cannot shift. A **locked** entry (approved or invoiced) is refused
  with a message saying so.
- `get_task_time {task_id}` — `ownTime` (this task alone) and
  `totalTimeIncludingSubIssues` (own plus every descendant), plus the per-person
  breakdown. The two totals are always labelled distinctly — quoting one as the
  other is the classic misread.

Durations come back **human-readable** (`"1h 30m"`), never as a raw minute count.

**Money is admin-only.** Rates, amounts and currency appear on a response only
when the caller is an org owner/admin on a cost-tracking project; for everyone
else the keys are simply **absent** — never zero. Members log and read their own
hours and see no money at all. Rates and billing items are managed in the web
app; there are no MCP tools for them.

## Hand a task to your coding agent

On a task's page, two icon buttons sit with the task's other actions (next to copy
link). They need the MCP server above to be connected in the agent: the prompt tells
the agent to read the task over it, and to stop and send you to the **MCP** page when
no `bugboard` server is connected. Neither button carries a token or any credential. A press is counted as an
`agent_handoff` product event (the target, `cursor` or `claude_code`, and no task
text; PRODUCT_EVENTS.md).
Code: `apps/web/src/lib/agent-handoff.ts` (the builders, unit-tested) and
`apps/web/src/components/tasks/task-detail-view/agent-handoff-actions.tsx`.

| Button | What it does | What the prompt holds |
|---|---|---|
| **Open in Cursor** | Opens `cursor://anysphere.cursor-deeplink/prompt?text=…`: Cursor starts with the prompt filled in and waits for you to send it. If no app handles the scheme the browser does nothing, so a toast says so and offers **Copy prompt**. | the task key (`bug-27`, `feat-3`, `change-290`), title, project name and id, global task id, the instruction to `get_task` it and report back with `comment_task`, and the description, shortened to fit |
| **Copy Claude Code command** | Copies `claude '<instruction>'` for a terminal where the `bugboard` MCP server is connected (`claude mcp add`, or the project `.mcp.json` above). | fixed wording, the key, the global id and the app origin: **no title, description or project name**, because those are written by teammates and each shell quotes differently. The agent reads them with `get_task`. The command is a single-quoted argument and is checked against a character allow-list before it is built; it is meant for POSIX shells and PowerShell, not `cmd.exe` |

Limits, from the vendors' documentation: Cursor's deeplink is at most 10,000
characters after encoding; the builder stays under 8,000 and cuts the description
by code point (so Greek, CJK and emoji text, which encode to several characters
each, fit too), ending it with a note that `get_task` returns the full text. Claude
Code's own `claude-cli://open?q=` link takes at most 5,000 characters and only works
once `claude` has run on that machine; it is not used. Control, zero-width and
bidirectional characters are stripped from everything put in a prompt. The
`https://cursor.com/link/prompt` twin of the Cursor link is not used, because it
would send the prompt (task text) to cursor.com.

A description can contain instructions meant for an agent; the prompt is shown in
the agent's input for review and is never auto-sent, and the agent applies its own
permission rules to whatever it does next.

## Resources

Read-only MCP resources expose individual records and guides:

- `bugboard://projects/{id}`
- `bugboard://tasks/{id}`
- `bugboard://guide/testing` — how the Testing feature works + which tools to use

## When to file

When you notice out-of-scope work — a bug, a follow-up, tech debt, a security
issue spotted in passing — file it as a task instead of dropping it. Run
`check_duplicates` first so you don't create a duplicate.
