MCP Server

The Buildd MCP server integrates with Claude Code, providing task coordination and workspace memory directly in your coding workflow.

Setup

Option 1: CLI command

claude mcp add --transport http buildd https://buildd.dev/api/mcp \
  --header "Authorization: Bearer bld_your_api_key"

Option 2: .mcp.json

Add to your project's .mcp.json:

{
  "mcpServers": {
    "buildd": {
      "type": "http",
      "url": "https://buildd.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer bld_your_api_key"
      }
    }
  }
}

Option 3: buildd login

If you use the buildd CLI, login auto-configures Claude Code:

curl -fsSL https://buildd.dev/install.sh | bash
buildd login

Restart Claude Code and the buildd tools will be available.

Workspace Detection

The MCP server resolves the workspace from the URL:

1. ?workspace=<id> query param — direct workspace ID
2. ?repo=<name> query param — matched against linked repositories
3. workspaceId in tool params (per-action override)
4. No filter — operations that require a workspace will prompt for workspaceId

When using buildd init <workspace-id>, the workspace is baked into the MCP URL automatically.

Tools

The server exposes two tools: buildd for task coordination and buildd_memory for workspace knowledge. Both use an action parameter to select the operation.

buildd — Task Coordination

Available actions depend on your account level (detected automatically from your API key).

Worker Actions (all accounts)

Admin Actions (admin-level API key only)

Examples

# Claim a task
buildd action=claim_task

# Report progress
buildd action=update_progress params={ workerId: "...", progress: 50, message: "Implemented auth middleware" }

# Create a PR and complete
buildd action=create_pr params={ workerId: "...", title: "feat: add auth", head: "feat/auth" }
buildd action=complete_task params={ workerId: "...", summary: "Added JWT auth middleware" }

# Submit a plan for review
buildd action=update_progress params={ workerId: "...", plan: "1. Add middleware\n2. Update routes\n3. Add tests" }

# Record a custom event
buildd action=emit_event params={ workerId: "...", type: "deploy", label: "Deployed to staging" }

buildd_memory — Workspace Knowledge

Backed by the Buildd Memory service. Memories are isolated per team and scoped by project within each team.

Examples

# Load project context
buildd_memory action=context

# Search for relevant context
buildd_memory action=search params={ query: "drizzle migrations", type: "gotcha" }

# Save a memory
buildd_memory action=save params={ type: "gotcha", title: "neon-http no transactions", content: "..." }

# Update a stale memory
buildd_memory action=update params={ id: "mem_xxx", content: "Updated guidance..." }

# Remove outdated memory
buildd_memory action=delete params={ id: "mem_xxx" }

MCP Resources

The server exposes read-only resources that MCP clients can read directly:

Observability Events

Workers can emit custom events to their timeline using emit_event, and read them back with query_events. Events piggyback on the existing milestones system — no additional setup needed.

Use cases:

• Record deployment milestones
• Track build/test results
• Log decision points for later review

Worker Workflow

The typical MCP workflow:

1. buildd action=list_tasks — see what's available
2. buildd action=claim_task — claim a task, read the included memory
3. git checkout <branch> — switch to the worker branch
4. buildd_memory action=search — search for context on unfamiliar files
5. Do the work, saving memories with buildd_memory action=save as you go
6. buildd action=update_progress — report at milestones (check for admin instructions in response)
7. git push — push your commits
8. buildd action=create_pr — create a pull request (use this instead of gh pr create)
9. buildd action=complete_task — mark the task as done