Connecting coding agents

A coding agent — Claude Code, Codex, anything that speaks MCP — works board tasks through a remote MCP server your API serves. The design and the decisions behind it are in agent-integration.md.

Everything between < and > is yours: <KEY> is your task-key prefix (config.keyPrefix), <owner>/<repo> your repository, <basePath> the prefix you mounted the board on, and <board-name> whatever you call the server when you register it.

• URL: https://<your-api-host>/api/mcp (local: http://localhost:4000/api/mcp)
• Transport: streamable HTTP, stateless (POST only, JSON responses)
• Auth: Authorization: Bearer <key> (or X-API-Key: <key>) with an API key of role agent. Admin logins and other keys are rejected, and an agent key cannot call any admin route.
• Rate limit: 60 calls per minute per key (HTTP 429 beyond that).

1. Get a key#

An admin mints one per agent (per person × tool) in the admin, or with POST <your admin API>/api-keys { "label": "Claude Code · <person>", "role": "agent" }. The label is the agent's display name on the board. The plaintext key is shown once; revoke it from the same screen when it leaks or is no longer used.

2. Connect#

Claude Code#

claude mcp add --transport http <board-name> https://<your-api-host>/api/mcp \
  --header "Authorization: Bearer <key>"

Check it with claude mcp list, or /mcp inside a session.

Codex#

~/.codex/config.toml:

[mcp_servers.<board-name>]
url = "https://<your-api-host>/api/mcp"
http_headers = { "Authorization" = "Bearer <key>" }

3. Branch convention#

Work each task on <key>-<n>-<slug>, e.g. <key>-42-fix-the-search, branched from origin/next (never from main) and opened as a PR against next. get_task_brief and claim_task return the exact name. The PR sync matches the <KEY>-<n> key in the branch, so the PR shows up on the task by itself; link_pr is for the cases it can't match.

Work ships in batches: see releases.md for the release flow. When your PR's checks are green, call add_to_release — that merges it into next so the reporter can test it. A stacked PR (one branched off another task's branch) is refused with stacked_pr until its parent lands; rebase it on origin/next after the parent is added.

4. Tools#

ref is always a task key (<KEY>-42) or its id. Errors come back as isError text, never as a crash, and every call is recorded (BacklogAgentAction) under the agent's key.

Entrega. Before moving a task to IN_REVIEW, hand it over: upload one to three screenshots with add_attachment (desktop and 390 px), then call submit_handoff with numbered steps somebody who does not program can follow, the preview URL when the change is visible on next, and a note about anything that can only be checked on production. move_task to IN_REVIEW still works without one, but it answers warning: "sin entrega: usa submit_handoff" and the person who asked for the task has nothing to test. The entrega shows on the task page, in get_task, and as a "Cómo probar" section in get_task_brief.

Statuses, in board order: BACKLOG → READY → IN_PROGRESS → BLOCKED → IN_REVIEW → DONE. BLOCKED means waiting on a person: ask_human puts the task there and remembers the column it came from (blockedFromStatus); the first teammate reply in the task comments sends it back to that column (or IN_PROGRESS). Moving a task out of BLOCKED by hand also forgets the origin. The brief shows it as **Estado:** Bloqueada (desde En progreso).

Acceptance criteria are stored as a markdown task list, and get_task_brief numbers them with their boxes (1. [x] …, 2. [ ] …). Tick one as soon as it is met with check_criteria({ ref, indexes: [2], done: true }); only those boxes change, and indexes out of range are ignored and listed in the result's ignored. set_acceptance_criteria replaces the whole list: a plain string keeps the box of an existing criterion with exactly the same (trimmed) text and starts unchecked otherwise, while { text, done } sets the box explicitly.

Paging list_tasks#

list_tasks (and GET <basePath>/tasks, which takes the same offset, limit and fields query params) answers { items, total, page, offset, limit, nextOffset }. A page is at most 100 cards (limit is clamped). To read everything, repeat the call with offset: nextOffset until nextOffset is null; total is the size of the whole filter. offset counts tasks, not pages, and wins over page.

fields: "ids" is the cheap mode: the whole filter as { id, key, status } rows, with no 100 cap (default and hard cap 2000 per call; nextOffset still says whether there are more). Use it to count or diff, then get_task only what you need.

5. Etiquette#

1. Read first: get_task_brief before touching code.
2. Claim before starting: claim_task, then work on the branch it returns.
3. Report progress often: add_progress at each meaningful step (what changed, what's next). The team reads it on the task page.
4. Use the brand kits: the admin's primitives live in <your admin kit> and the storefront's in <your storefront kit> (your brand classes). Never hand-style a button, a chip or an input — extend the kit instead. app_context answers "botón", "chip" or "button" with the exact component and its file, and get_task_brief names the likely ones for the app your task touches.
5. Hand it over: add_attachment + submit_handoff before review — a change nobody can test is not finished.
6. Ask when blocked: ask_human with a concrete question, then poll read_replies with the since of your question instead of guessing.
7. Finish in review: open the PR, link_pr if the branch didn't match, move_task to IN_REVIEW, and add_to_release once the checks are green.
8. File what you find: out-of-scope bugs or follow-ups go in create_task, not in the current PR.

6. What agents cannot do#

• Move a task to RELEASED or DONE. The release assigns "En producción" when it ships, and the person who asked for the task closes it after checking it on production.
• Open, ship or record a release. create_release, ship_release and record_ship exist only for an automation key, which is a person's own admin-level key.
• Delete tasks, archive epics, bulk-edit, verify, answer move requests or edit releases: those tools exist only for an automation key.
• Edit or delete somebody else's comment or attachment.
• Dispatch agents, use the AI chat, conversations or proposals, or read the notifications, usage or repository routes: not exposed over MCP.
• Reach the admin API with an agent key, or mint/revoke keys.

7. Dispatch: "Enviar a agente"#

Instead of an agent pulling work, the board can push a task to one. From the task page (or a backlog row), Enviar a agente › Claude | Codex calls POST <basePath>/tasks/:id/dispatch with { "agent": "claude" | "codex" }:

1. Issue mirror. The first time, the API creates a GitHub issue on <owner>/<repo> titled <KEY>-<n> · <título>. Its body is the same brief as get_task_brief plus a footer linking back to the task, and it gets the labels tablero and <type>. Later dispatches update the title and body and keep the existing labels. If the mirrored issue was deleted, a new one is created. The task stores githubIssueNumber / githubIssueUrl.
2. Trigger.
   • Claude: a comment @claude Trabaja esta tarea siguiendo el brief; …. The workflow .github/workflows/claude.yml (Claude Code Action on a hosted runner) answers it. The run has the the board MCP configured, claims the task, reports progress, opens the PR on <key>-<n>-<slug> and moves the task to IN_REVIEW.
   • Codex: adds the label codex. The issue is then assigned to GITHUB_CODEX_ASSIGNEE when that env var is set on the API; otherwise the API comments @codex … with the same instruction.
3. Trail. The task gets a comment "Enviada a Claude/Codex · issue #n", and the activity feed gets a backlog.task.dispatch row.

Response: { taskId, key, agent, issueNumber, issueUrl, created, trigger: "comment" | "assignee" }. Errors:

• 409: the GitHub token can't write issues (see setup step a).
• 503: GitHub isn't configured.
• 502: any other GitHub failure.

Running on subscriptions keeps per-token API cost at zero. The only cost is hosted Actions minutes.