Skip to main content

Use Broome Projects MCP

Broome Projects MCP is a read-only local MCP server that lets an AI agent inspect Broome Kanban work through natural-language questions. It can show what is ready, blocked, assigned to you, expensive, highest-impact to unblock, or inside one known card without giving the agent direct database access.

The package is currently private and unpublished. Install it from a local checkout.

Prerequisites​

  • Node.js 20 or newer.
  • A Broome PAT with the kanban:read scope. Use the secret beginning with brm_pat_ (or the legacy ftag_pat_, still valid), not the token UUID shown by internal administration screens.
  • Access to the target Broome environment.

Build the local checkout​

cd /absolute/path/to/broome-projects-mcp
npm ci
npm run build
npm test
npm run typecheck

Register it with Claude Code​

claude mcp add broome-projects-mcp \
  -e FILETAG_API_KEY=<your-brm-pat> \
  -- node /absolute/path/to/broome-projects-mcp/dist/index.js

For protected staging:

claude mcp add broome-projects-mcp \
  -e FILETAG_API_URL=https://staging.broometech.com \
  -e FILETAG_API_KEY=<your-brm-pat> \
  -e VERCEL_AUTOMATION_BYPASS_SECRET=<your-bypass-secret> \
  -- node /absolute/path/to/broome-projects-mcp/dist/index.js

Never commit either secret. The Vercel bypass is needed only for an environment protected by Vercel Deployment Protection.

Ask naturally​

You do not need to know the MCP tool names. Ask questions such as:

  • “Which CI-1 subtasks are still open?”
  • “What do I need to implement in CI-11?”
  • “What is blocking AUTH-4?”
  • “Considering my cards and unassigned work, what should I pick up next?”
  • “What should I finish first to unblock the most work?” — answered by one unlock call. Each card reports how many blocked cards become ready the moment it is done, and how many downstream cards depend on it transitively.
  • “What has the agent changed recently?” — answered by one activity call. Each entry says what happened, to which card, whether it succeeded, and which token issued it when the call carried one.
  • “Find cards or documents mentioning device authorization.”

For a known identifier such as CI-11, the MCP reads the card's structured neighborhood in one call: subtasks, completion state, dependencies, dependents, document summaries, linked files, and attachments. It fetches a full subtask document only when the answer needs its implementation detail.

How unlock impact is measured​

Two different numbers travel with every card:

  • Becomes ready counts the direct dependents that are startable the moment this card is done. A dependent still waiting on another unfinished card is not counted.
  • Downstream reach counts the distinct downstream cards that depend on this one, directly or through a chain, once each. It is a measure of how much work sits behind this card — not a prediction that all of it becomes ready.

Both numbers are counted only over the cards you can see, at every step of the chain. Work that is reachable only through a card on a board you cannot open is left out, so both numbers are lower bounds rather than a complete picture. This is deliberate: the privacy boundary is preserved even at the cost of an undercount. Completed cards report zero and are never counted as downstream of anything.

What search covers​

Keyword search covers:

  • card titles and descriptions;
  • subtask titles;
  • subtask-document names and text content;
  • attached file names.

It does not search binary file contents, external websites, or semantic similarity. Phase 1 uses lexical Postgres full-text search; pgvector hybrid search is planned separately.

What the activity feed covers​

The activity feed reads the Kanban API's audit trail, newest first, and can be narrowed by action, outcome, or target type. Four things are worth knowing before you rely on it.

It covers only what you can see. Every entry is filtered by workspace membership and by board visibility. An entry whose card sits on a board you cannot open does not appear at all.

It records API calls, not every possible change. Writes that go through the Kanban API's audited operations show up. A writer that updates its table directly does not — the older in-app comment action is the known example and never appears here. Treat a missing entry as "not recorded", never as proof that nothing happened.

A token names the caller; its absence names nobody. An entry that carries a token came in over the API, and the token identifies who is responsible for it. An entry with no token only means none was recorded — it is not evidence that a person made the change in the browser.

Card and subtask names are resolved when you read. Each entry keeps the target's stable id, and the readable name is looked up from the record as it stands right now. Rename a subtask and every older entry about it reads with the new name. The facts that do not move — what happened, to which id, with what outcome, and when — are the ones stored with the entry.

Entries link back to the board. Each entry carries card_id and board_id when the target's board is visible to you, so a feed line can be opened directly at …/boards/{board_id}?card={card_id}. Entries without a board — workstream changes, or failed calls whose target never resolved — carry null for both, and a hidden board looks exactly the same as no board at all.

Troubleshooting​

401 Invalid or missing token​

Confirm FILETAG_API_KEY contains the PAT secret beginning with brm_pat_ (or the legacy ftag_pat_, still valid). A token UUID is an identifier, not a bearer credential.

403 Insufficient scope​

Issue a PAT that includes kanban:read.

404 Not found on staging​

The token may not be admitted by the current canary rollout. This is separate from authentication and must be resolved by the staging administrator.

401 Protected deployment​

The request reached Vercel Deployment Protection before Broome. Configure VERCEL_AUTOMATION_BYPASS_SECRET for protected staging only.

The old MCP name or path still appears​

Remove the old registration and add broome-projects-mcp using the renamed checkout path. The active binary must be /absolute/path/to/broome-projects-mcp/dist/index.js.

Current limits​

  • Read-only: the MCP cannot create, move, complete, or edit work.
  • The single-card intel enrichment can miss its aggregate intel row in a workspace with more than 200 accessible cards; structural card data still returns.
  • Search is lexical, not semantic.
  • The package is private and unpublished, so local checkout registration is required.