blue/docs/mcp/integration.md

Blue MCP Integration Guide

Set up Blue as an MCP server for Claude Code.

Prerequisites

1. Install Blue CLI

   cargo install --path apps/blue-cli
   

   Or build from source:

   cargo build --release
   

2. Initialize a realm (if not already done)

   blue realm admin init --name mycompany
   

3. Join your repo to the realm

   cd /path/to/your/repo
   blue realm admin join mycompany
   

Claude Code Configuration

Add Blue to your Claude Code MCP configuration:

macOS / Linux

Edit ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "blue": {
      "command": "blue",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Or with explicit path:

{
  "mcpServers": {
    "blue": {
      "command": "/path/to/blue",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Windows

Edit %APPDATA%\claude-code\mcp.json:

{
  "mcpServers": {
    "blue": {
      "command": "blue.exe",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Verification

After configuration, restart Claude Code and verify the tools are available:

Human: What realm tools do you have?

Claude: I have access to Blue's realm coordination tools:
- realm_status - Get realm overview
- realm_check - Validate contracts
- contract_get - Get contract details
- session_start - Begin work session
- session_stop - End session
- realm_worktree_create - Create worktrees
- realm_pr_status - Check PR readiness
- notifications_list - List notifications

Usage Examples

Check Realm Status

Human: What's the status of my realm?

Claude: [calls realm_status with cwd=/path/to/repo]

You're in the "aperture" realm, working in the "blue" repo.
There's one domain (s3-access) with blue as provider and fungal as consumer.
No active session.

Start a Work Session

Human: Start a session for RFC 0042

Claude: [calls session_start with cwd=/path/to/repo, active_rfc="rfc-0042"]

Session started. You're watching 1 imported contract in the s3-access domain.
I'll track changes and notify you if contracts you depend on are updated.

Create Worktrees for Multi-Repo Work

Human: Set up worktrees for my RFC

Claude: [calls realm_worktree_create with rfc="rfc-0042"]

Created worktrees for blue and fungal (domain peers via s3-access).
Paths:
- ~/.blue/worktrees/aperture/rfc-0042/blue
- ~/.blue/worktrees/aperture/rfc-0042/fungal

Ready to start working.

Check PR Readiness

Human: Are we ready to merge?

Claude: [calls realm_pr_status with rfc="rfc-0042"]

Not quite:
- blue: 2 commits to push, PR #42 is open
- fungal: 3 uncommitted changes, no PR yet

Commit your changes in fungal, push both repos, then create a PR for fungal.

Validate Before CI

Human: Will CI pass?

Claude: [calls realm_check]

All checks pass. No errors or warnings.
Schema hashes verified for all contracts.

Workflow Integration

Typical Development Flow

1. Start session when beginning work

   Human: I'm starting work on the new API
   Claude: [calls session_start]
   

2. Create worktrees for multi-repo changes

   Human: Set up worktrees for rfc-new-api
   Claude: [calls realm_worktree_create]
   

3. Check status as you work

   Human: Any updates I should know about?
   Claude: [calls realm_status]
   

4. Validate before committing

   Human: Is everything valid?
   Claude: [calls realm_check]
   

5. Check PR readiness before merging

   Human: Ready to merge?
   Claude: [calls realm_pr_status]
   

6. End session when done

   Human: Done for today
   Claude: [calls session_stop]
   

Notification Handling

Notifications piggyback on realm_status and realm_check calls. When a contract you depend on changes, you'll see:

Human: What's our realm status?

Claude: [calls realm_status]

You're in aperture/blue. 1 pending notification:
- s3-permissions contract was updated from 1.0.0 to 1.1.0 by fungal

Review the changes with contract_get to see what changed.

Daemon Integration

For real-time notifications, start the Blue daemon:

blue daemon start

The daemon:

• Tracks active sessions across repos
• Stores notifications in ~/.blue/daemon.db
• Cleans up expired notifications (7+ days)

Without the daemon, notifications are stored locally and checked on each tool call.

Troubleshooting

"Not in a realm repo"

Your current directory doesn't have a .blue/config.yaml file.

cd /path/to/your/repo
blue realm admin join <realm-name>

"Failed to get daemon paths"

The ~/.blue directory doesn't exist or isn't accessible.

mkdir -p ~/.blue

"Failed to open daemon database"

The daemon database is corrupted or locked.

rm ~/.blue/daemon.db
blue daemon start

Tools not appearing in Claude Code

1. Check MCP configuration syntax
2. Verify blue binary is in PATH or use absolute path
3. Restart Claude Code after configuration changes
4. Check Claude Code logs for MCP errors

Advanced Configuration

Custom Blue Path

If Blue is installed in a non-standard location:

{
  "mcpServers": {
    "blue": {
      "command": "/opt/blue/bin/blue",
      "args": ["mcp"]
    }
  }
}

Environment Variables

Pass environment variables to the MCP server:

{
  "mcpServers": {
    "blue": {
      "command": "blue",
      "args": ["mcp"],
      "env": {
        "BLUE_HOME": "/custom/path",
        "RUST_LOG": "debug"
      }
    }
  }
}

Multiple Realms

Blue automatically detects the realm from your current directory. Each repo's .blue/config.yaml specifies its realm membership.

To work across realms, just change directories:

Human: What realm is this?
Claude: [calls realm_status from /projects/blue]
You're in the aperture realm.