Introducing Bureau MCP
Oct 7, 2025
My agentic workflow involves subagents reading and writing report files, in a directory structure like this:
_tasks/
├── 2025-10-01-implement-feature/
│ ├── 001-user-request.md
│ ├── 002-plan.md
│ ├── 003-implementation.md
│ └── 004-tests.md
├── 2025-10-01b-fix-bug/
│ ├── 001-bug-report.md
│ └── 002-fix.md
└── 2025-10-02-refactor/
├── 001-analysis.md
└── 002-plan.md
Unfortunately, Claude struggles to maintain consistent file numbering and folder organization when managing multi-step tasks.
Agents would often:
- Mess up sequential numbering
- Switch to new folders unexpectedly
- Lose track of which task is current
- Miss later files on long tasks by virtue of doing
ls ... | head -50
- Overwrite older reports instead of adding new ones
This happened so frequently that it was pretty damn annoying.
So I’ve built a tiny MCP server to help with it, bureau-mcp.
The server stores reports under _tasks
. It (1) maintains which task is current (via _tasks/current
symlink), (2) lists all report files for the agent to see (because they sometimes do ls | head -50
and miss later files on long tasks), and, most importantly, (3) tells the agent which report file to write to.
Install it via:
claude mcp add bureau --scope user -- npx -y bureau-mcp
then add it to your agentic instructions by asking Claude to:
/hr Update CLAUDE.md and all agents to use bureau MCP server instead of finding tasks and report files themselves.
Rules for agents:
1. When agent starts, call current_task. Planning and review agents (Don, Joel, Linus) read all reports. Implementation agents only read the latest plans and subsequent implementation reports.
2. When agent is finishing, call start_new_report_file and write the report to that file. Use short suffix representing the agent and its outcome ('don-plan', 'joel-plan', 'linus-plan-review', etc)
3. The first agent after a user request does start_new_report_file with a suffix of 'user-request', 'user-revision' or 'user-bug-report', 'user-complaint', etc, and writes out the user's message in there.
4. /do should call start_new_task. (Or, if user is asking to continue a certain task that's not current, /do and /rev can call switch_task.)
5. Agents only write files to report dir via start_new_report_file, never under any other names. Agents never list report directories, they always rely on what current_task returns.
(if you don’t have /hr
command, well first you should, and second you can just skip it and ask Claude natively.)
Done and done. No more reporting woes observed. Latest agent definitions and commands are in andreyvit/claude-code-setup
.
FAQ
Have you seen claude-task-master?
🤮.
I.e. it’s a weird project that seems to be solving the kinds of problems that real codebases don’t have, and doesn’t solve the problems that actually arise. And it is horribly overengineered to boot.
Do your agents really work for so long as to require triple-digit report files?
Yes, some longer tasks with a bunch of revisions get over a hundred rounds.
Do you really run agents unattended for hours?
For hours, yes. Unattended, no. I check back periodically and, if they’re doing shit, give them a /rev
command with instructions.
A rule of thumb is to check back maybe 30 minutes after launching a task, and every hour after that. (I hope newer models will shrink these timelines.)
Your workflow must be horribly inefficient if it runs slower than a human
It is horribly inefficient, but that compute comes cheaply so far.