How to use Briefboard with Claude Code (MCP)

Briefboard ships with an MCP server, which means Claude Code can read and write your project directly — no copy-pasting tasks into a prompt. The agent works from the same milestones, specs, and tasks your team does.

This guide covers the setup, then walks through a complete real session: the agent pulls its next task, reads the spec behind it, implements, and reports back — while your board stays accurate without anyone touching it.

What MCP gives you

MCP (the Model Context Protocol) is a standard way for AI tools to talk to external systems. Briefboard exposes its project data through an MCP server, so a connected agent can:

• Pull the next priority task assigned to it.
• Read a task's full brief and discussion history.
• Fetch the milestone and its specs.
• Update task status and post progress comments.

The difference with pasting context by hand isn't convenience — it's freshness. A pasted brief is stale the moment a teammate reprioritizes. An agent on MCP asks the board at the moment it starts working.

Connect Claude Code

One command:

claude mcp add --transport http briefboard https://app.briefboard.io/mcp/briefboard

The server is a streamable HTTP endpoint protected by OAuth with dynamic client registration: an authorization screen opens in your browser, you approve it, and the connection is saved. No API keys to create, no tokens to rotate.

Using Cursor or OpenAI Codex instead? The MCP connection guide has the equivalent config for each client.

During local development, connect over http:// rather than https:// — some MCP clients use Node's certificate store and will reject a self-signed certificate.

A real session, start to finish

Here's what a working session actually looks like on a project — call it Atlas — where a milestone is in flight and tasks are assigned to the agent.

1. The agent asks for work

You open Claude Code and type one line:

> Get my next Briefboard task and implement it.

The agent calls get-next-task and gets back the highest-priority task assigned to it — not a guess, the same ordering your team sees on the board:

● briefboard - get-next-task
  ⎿ BB-T204 — Add retry logic to webhook delivery
    Milestone: MA-M1 "Public launch" (at risk)
    Priority: high · Status: todo

2. It pulls the full brief

A task title isn't enough to implement against. The agent calls get-task-prompt, which returns an implementation prompt pre-filled with everything the board knows: the task description — checklist of expected outcomes included — the milestone objective, and the specs linked to that milestone.

● briefboard - get-task-prompt
  ⎿ ## Task: Add retry logic to webhook delivery
    Failed webhook deliveries are currently dropped. Add exponential
    backoff with a maximum of 5 attempts.

    - [ ] Failed deliveries retry with exponential backoff
    - [ ] Delivery gives up after 5 attempts and marks the webhook failed
    - [ ] Each attempt is logged with its attempt number

    ## Linked spec: webhook-delivery-contract (v3)
    Retries MUST reuse the original event payload. The receiving
    endpoint sees an `X-Attempt` header…

That last block is the part copy-paste workflows always lose: the spec. In Briefboard, specs are versioned documents linked to milestones — an API contract, a data model, acceptance rules. The agent doesn't work from its memory of your architecture; it works from the document your team agreed on. If it needs more, get-milestone-specs and get-spec are one call away.

3. It works — and claims the task

Before writing code, the agent marks the task in progress so the board reflects reality:

● briefboard - update-task-status (BB-T204, in_progress)
  ⎿ Task BB-T204 is now in progress

Anyone looking at the Atlas board right now — including your non-technical teammates — sees BB-T204 moving, with no standup required. Then the agent does what Claude Code does: reads the codebase, writes the retry logic, runs the tests.

4. It reports where the team reads

When the work is done, the agent doesn't summarize into the void of a terminal scrollback. It posts to the task's technical channel:

● briefboard - add-task-comment (BB-T204, channel: technical)
  ⎿ Implemented exponential backoff (base 2s, max 5 attempts) in
    WebhookDeliveryJob. Added X-Attempt header per spec v3. 14 new
    tests, all green. Files: app/Jobs/WebhookDeliveryJob.php,
    tests/Feature/WebhookRetryTest.php

…and marks the task done:

● briefboard - update-task-status (BB-T204, done)
  ⎿ Task BB-T204 is now done

Total human input for the whole loop: one sentence. Total board updates done by hand: zero.

Why this survives multiple sessions

The quiet superpower of this setup is that the state lives on the board, not in the conversation. Close Claude Code, open it tomorrow, ask for the next task — the agent picks up exactly where the project is, because the project is the source of truth. The same goes for running several agents, or an agent and a human, on the same milestone: they coordinate through task assignment and status, the way teammates do, instead of through a shared prompt document that someone forgot to update.

That's also why the loop scales down gracefully. Solo dev, one project, agent doing most of the implementation? The board is your memory between sessions. Team of eight with two agents in the mix? Same board, same rules — agents respect the same roles, permissions, and plan limits as any member.

If something doesn't work

Three things cover most setup friction:

• The authorization screen never opens. Check that you're connecting to the exact endpoint https://app.briefboard.io/mcp/briefboard with --transport http — the server streams over HTTP; an stdio configuration won't connect.
• The agent sees no tasks. get-next-task returns tasks assigned to the connected member. If the queue is empty, assign the agent a task on the board — or ask it to call list-tasks and pick one up.
• A tool call is refused. Tools respect the same permissions and quotas as the web app. An agent acting as a member of one project can't touch another, and Free-plan limits apply to agents too. That's a feature: your roles define the blast radius.

Keep the human in the loop

The agent can move tasks and leave comments, but the important decisions — what to build, when something is truly done, when to merge — stay with you. Nothing in the loop above merges code or closes a milestone; it keeps the shared picture honest while the agent does the heavy lifting.

That's the whole idea behind AI-driven development on Briefboard: give the agent real context, let it work, and keep humans focused on the outcomes. If you want the full tool list — planning, specs, triage — it's in the MCP tools guide.