Hive MCP Server

The Hive MCP server exposes Agent Hive functionality as MCP tools, enabling AI agents like Claude to programmatically manage projects through standardized tool interfaces.

Overview

MCP (Model Context Protocol) provides a standardized way for AI agents to interact with external tools. The Hive MCP server exposes project management operations as callable tools.

Setup

Configuration

Add the Hive MCP server to your Claude configuration:

For Claude Desktop (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hive": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.hive_mcp"],
      "cwd": "/path/to/agent-hive",
      "env": {
        "HIVE_BASE_PATH": "/path/to/agent-hive",
        "COORDINATOR_URL": "http://localhost:8080"
      }
    }
  }
}

For DevContainer (.devcontainer/devcontainer.json):

{
  "mcpServers": {
    "hive": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.hive_mcp"]
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | HIVE_BASE_PATH | Root path of the hive | Current directory | | COORDINATOR_URL | URL of coordination server | Not set (optional) |

Available Tools

Project Discovery

`list_projects`

List all projects in the hive with their metadata.

{
  "name": "list_projects",
  "arguments": {}
}

Response:

{
  "success": true,
  "data": {
    "count": 3,
    "projects": [
      {
        "project_id": "demo",
        "status": "active",
        "owner": null,
        "priority": "medium",
        "tags": ["example"]
      }
    ]
  }
}

`get_ready_work`

Get projects ready for an agent to claim.

{
  "name": "get_ready_work",
  "arguments": {}
}

Returns projects that are:

Status: active
Not blocked
No current owner
Dependencies satisfied

`get_project`

Get full details of a specific project.

{
  "name": "get_project",
  "arguments": {
    "project_id": "demo"
  }
}

Response includes:

All metadata fields
Full markdown content
Dependency information

Project Ownership

`claim_project`

Claim a project by setting ownership.

{
  "name": "claim_project",
  "arguments": {
    "project_id": "demo",
    "agent_name": "claude-sonnet-4"
  }
}

Success response:

{
  "success": true,
  "data": {
    "project_id": "demo",
    "owner": "claude-sonnet-4"
  }
}

Failure (already claimed):

{
  "success": false,
  "error": "Project already claimed by grok-beta"
}

`release_project`

Release ownership of a project.

{
  "name": "release_project",
  "arguments": {
    "project_id": "demo"
  }
}

Status Management

`update_status`

Update the status of a project.

{
  "name": "update_status",
  "arguments": {
    "project_id": "demo",
    "status": "completed"
  }
}

Valid statuses:

active - Ready for work
pending - Not yet started
blocked - Waiting for external input
completed - All tasks done

`add_note`

Add a timestamped note to Agent Notes section.

{
  "name": "add_note",
  "arguments": {
    "project_id": "demo",
    "agent": "claude-sonnet-4",
    "note": "Completed research phase. Found 5 relevant sources."
  }
}

Dependency Analysis

`get_dependencies`

Get dependency information for a project.

{
  "name": "get_dependencies",
  "arguments": {
    "project_id": "demo"
  }
}

Response:

{
  "success": true,
  "data": {
    "is_blocked": false,
    "reasons": [],
    "blocking_projects": [],
    "in_cycle": false,
    "cycle": []
  }
}

`get_dependency_graph`

Get full dependency graph for all projects.

{
  "name": "get_dependency_graph",
  "arguments": {}
}

Coordinator Integration

These tools require COORDINATOR_URL to be configured.

`coordinator_status`

Check if coordination server is available.

{
  "name": "coordinator_status",
  "arguments": {}
}

`coordinator_claim`

Claim via coordination server (prevents conflicts).

{
  "name": "coordinator_claim",
  "arguments": {
    "project_id": "demo",
    "agent_name": "claude-sonnet-4",
    "ttl_seconds": 3600
  }
}

`coordinator_release`

Release claim via coordination server.

{
  "name": "coordinator_release",
  "arguments": {
    "project_id": "demo"
  }
}

`coordinator_reservations`

Get all active reservations.

{
  "name": "coordinator_reservations",
  "arguments": {}
}

Tool Reference

| Tool | Description | Required Args | |------|-------------|---------------| | list_projects | List all projects | None | | get_ready_work | Find claimable projects | None | | get_project | Get project details | project_id | | claim_project | Claim ownership | project_id, agent_name | | release_project | Release ownership | project_id | | update_status | Change project status | project_id, status | | add_note | Add agent note | project_id, agent, note | | get_dependencies | Check blocking status | project_id | | get_dependency_graph | Full dependency view | None | | coordinator_status | Coordinator health | None | | coordinator_claim | Real-time claim | project_id, agent_name | | coordinator_release | Real-time release | project_id | | coordinator_reservations | Active reservations | None |

Response Format

All tools return a standardized response:

{
  "success": true|false,
  "data": { ... },      // Present on success
  "error": "message"    // Present on failure
}

Workflow Example

Starting Work on a Project

1. list_projects()           # See what's available
2. get_ready_work()          # Find claimable projects
3. get_project("my-proj")    # Review project details
4. claim_project("my-proj", "claude-sonnet-4")
5. [Do the work]
6. add_note("my-proj", "claude-sonnet-4", "Completed task X")
7. update_status("my-proj", "completed")
8. release_project("my-proj")

With Coordinator (Parallel-Safe)

1. coordinator_status()      # Verify coordinator is up
2. coordinator_claim("my-proj", "claude-sonnet-4", 3600)
3. claim_project("my-proj", "claude-sonnet-4")  # Also update AGENCY.md
4. [Do the work]
5. release_project("my-proj")
6. coordinator_release("my-proj")

Best Practices

Check ready work first - Use get_ready_work to find available projects
Read before claiming - Use get_project to understand the work
Use coordinator for parallel agents - Prevents race conditions
Add notes for transparency - Document your progress
Release when done - Don't hold claims unnecessarily
Handle errors gracefully - Check success field in responses

Troubleshooting

"Project not found"

Verify project_id matches exactly (case-sensitive).

"Project already claimed"

Another agent owns the project. Use get_project to see current owner.

"Coordinator unavailable"

Check COORDINATOR_URL is set
Verify coordinator server is running
Test with coordinator_status tool

"Failed to update project"

Verify AGENCY.md file exists
Check file permissions
Ensure path is within HIVE_BASE_PATH