Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.
The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).
Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.
Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).
Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
3.4 KiB
3.4 KiB
| title |
|---|
| MCP Server |
Use beads in MCP-only environments.
When to Use MCP
Use MCP server when CLI is unavailable:
- Claude Desktop (no shell access)
- Sourcegraph Amp without shell
- Other MCP-only environments
Prefer CLI + hooks when shell is available - it's more context efficient.
Installation
Using uv (Recommended)
uv tool install beads-mcp
Using pip
pip install beads-mcp
Configuration
Claude Desktop (macOS)
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Claude Desktop (Windows)
Add to %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"beads": {
"command": "beads-mcp"
}
}
}
Sourcegraph Amp
Add to MCP settings:
{
"beads": {
"command": "beads-mcp",
"args": []
}
}
VS Code / GitHub Copilot
Create .vscode/mcp.json in your project:
{
"servers": {
"beads": {
"command": "beads-mcp"
}
}
}
For all projects: Add to VS Code user-level MCP config:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Code/User/mcp.json |
| Linux | ~/.config/Code/User/mcp.json |
| Windows | %APPDATA%\Code\User\mcp.json |
{
"servers": {
"beads": {
"command": "beads-mcp",
"args": []
}
}
}
Note: Requires VS Code 1.96+ with MCP support enabled.
See GitHub Copilot Integration for complete setup guide.
Available Tools
The MCP server exposes these tools:
| Tool | Description |
|---|---|
ready |
Show ready work (no open blockers) |
list |
List issues with filters |
show |
Show issue details, dependencies, and dependents |
create |
Create a new issue |
claim |
Atomically claim an issue |
update |
Update an issue |
close / reopen |
Close or reopen an issue |
dep |
Manage dependencies |
comment / comments |
Add or list comments |
note |
Append to an issue's notes |
blocked |
Show blocked issues and their blockers |
stats / context |
Database stats and workspace context |
admin |
Administrative operations |
discover_tools / get_tool_info |
Tool discovery and schemas |
There is no MCP sync tool — syncing stays on the CLI (bd dolt push /
bd dolt pull).
Usage
Once configured, use naturally:
Create an issue for fixing the login bug with priority 1
The MCP server translates to appropriate bd commands.
Trade-offs
| Aspect | CLI + Hooks | MCP Server |
|---|---|---|
| Context overhead | ~1-2k tokens | 10-50k tokens |
| Latency | Direct calls | MCP protocol |
| Setup | Hooks config | MCP config |
| Availability | Shell required | MCP environments |
Troubleshooting
Server won't start
Check if beads-mcp is in PATH:
which beads-mcp
If not found:
# Reinstall
pip uninstall beads-mcp
pip install beads-mcp
Tools not appearing
- Restart Claude Desktop
- Check MCP config JSON syntax
- Verify server path
Permission errors
# Check directory permissions
ls -la .beads/
# Initialize if needed
bd init --quiet
See Also
- Claude Code - CLI integration
- Installation - Full install guide