beads/docs/integrations/mcp-server.md
Chris Sells 5c2fe0d496 docs: loss-check merge legacy docs/ originals into the site pages
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).
2026-07-12 10:37:07 -07:00

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

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

  1. Restart Claude Desktop
  2. Check MCP config JSON syntax
  3. Verify server path

Permission errors

# Check directory permissions
ls -la .beads/

# Initialize if needed
bd init --quiet

See Also