beads/integrations/beads-mcp/SETUP_DAEMON.md

Setting Up Daemon-Based MCP Server

Quick Start

Replace your multiple MCP server configs with a single daemon-based one:

1. Claude Desktop Config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp",
      "env": {
        "BEADS_USE_DAEMON": "1"
      }
    }
  }
}

Remove old configs like beads-wyvern, beads-adar, etc.

2. Start the Daemon

In your beads project directory:

bd daemon start

The daemon will:

• Listen on .beads/bd.sock (Windows: file stores loopback TCP metadata)
• Route operations to correct database based on request cwd
• Handle multiple repos simultaneously

3. Test It

# Test with beads repo
cd ~/src/vc/adar/beads
bd list

# Test with another repo
cd ~/src/vc/wyvern
bd list

# Both should show correct issues for their respective databases

4. Restart Claude Desktop

After updating the config, restart Claude Desktop to load the new MCP server configuration.

How It Works

Claude/Amp → Single MCP Server → Daemon Client → Daemon → Correct Database
                  ↓ 
          Uses set_context to pass workspace_root
                  ↓
          Daemon uses cwd to find .beads/*.db

• No more multiple MCP servers - one server handles all repos
• Per-request routing - daemon finds correct database for each operation
• Automatic fallback - if daemon not running, falls back to CLI mode
• Concurrent access - daemon handles multiple repos at once

Advanced Configuration

Optional Environment Variables

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp",
      "env": {
        "BEADS_USE_DAEMON": "1",
        "BEADS_REQUIRE_CONTEXT": "1",
        "BEADS_ACTOR": "claude"
      }
    }
  }
}

• BEADS_USE_DAEMON - Use daemon (default: 1)
• BEADS_REQUIRE_CONTEXT - Enforce set_context before writes (default: 0)
• BEADS_ACTOR - Actor name for audit trail (default: $USER)

Disable Daemon (Fallback to CLI)

If you want to temporarily use CLI mode:

{
  "env": {
    "BEADS_USE_DAEMON": "0"
  }
}

Daemon Management

# Start daemon
bd daemon start

# Check status
bd daemon status

# View logs
bd daemon logs

# Stop daemon
bd daemon stop

# Restart daemon
bd daemon stop && bd daemon start

Troubleshooting

"Daemon not running" errors

Start the daemon in your beads project:

cd ~/src/vc/adar/beads
bd daemon start

Wrong database being used

1. Check where daemon is running:

   bd daemon status
   

2. Use set_context tool in Claude to set workspace root:

   set_context /path/to/your/project
   

3. Verify with where_am_i tool

Multiple repos not working

Ensure:

• Daemon is running in a parent directory that can reach all repos
• Each repo has .beads/*.db properly initialized
• MCP server is passing correct workspace_root via set_context

Migration from Multi-Server Setup

Old Config (Remove This)

{
  "mcpServers": {
    "beads-adar": {
      "command": "beads-mcp",
      "env": {
        "BEADS_DB": "/path/to/adar/.beads/bd.db"
      }
    },
    "beads-wyvern": {
      "command": "beads-mcp",
      "env": {
        "BEADS_DB": "/path/to/wyvern/.beads/wy.db"
      }
    }
  }
}

New Config (Use This)

{
  "mcpServers": {
    "beads": {
      "command": "beads-mcp",
      "env": {
        "BEADS_USE_DAEMON": "1"
      }
    }
  }
}

Benefits

✅ Single MCP server for all repos ✅ No manual BEADS_DB configuration per repo ✅ Automatic context switching ✅ Better performance (no process spawning per operation) ✅ Concurrent multi-repo operations ✅ Simpler configuration