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):

json
1{
2  "mcpServers": {
3    "hive": {
4      "command": "uv",
5      "args": ["run", "python", "-m", "src.hive_mcp"],
6      "cwd": "/path/to/agent-hive",
7      "env": {
8        "HIVE_BASE_PATH": "/path/to/agent-hive",
9        "COORDINATOR_URL": "http://localhost:8080"
10      }
11    }
12  }
13}

For DevContainer (.devcontainer/devcontainer.json):

json
1{
2  "mcpServers": {
3    "hive": {
4      "command": "uv",
5      "args": ["run", "python", "-m", "src.hive_mcp"]
6    }
7  }
8}

Environment Variables

Available Tools

Project Discovery

list_projects

List all projects in the hive with their metadata.

json
1{
2  "name": "list_projects",
3  "arguments": {}
4}

Response:

json
1{
2  "success": true,
3  "data": {
4    "count": 3,
5    "projects": [
6      {
7        "project_id": "demo",
8        "status": "active",
9        "owner": null,
10        "priority": "medium",
11        "tags": ["example"]
12      }
13    ]
14  }
15}

get_ready_work

Get projects ready for an agent to claim.

json
1{
2  "name": "get_ready_work",
3  "arguments": {}
4}

Returns projects that are:

• Status: active
• Not blocked
• No current owner
• Dependencies satisfied

get_project

Get full details of a specific project.

json
1{
2  "name": "get_project",
3  "arguments": {
4    "project_id": "demo"
5  }
6}

Response includes:

• All metadata fields
• Full markdown content
• Dependency information

Project Ownership

claim_project

Claim a project by setting ownership.

json
1{
2  "name": "claim_project",
3  "arguments": {
4    "project_id": "demo",
5    "agent_name": "claude-sonnet-4"
6  }
7}

Success response:

json
1{
2  "success": true,
3  "data": {
4    "project_id": "demo",
5    "owner": "claude-sonnet-4"
6  }
7}

Failure (already claimed):

json
1{
2  "success": false,
3  "error": "Project already claimed by grok-beta"
4}

release_project

Release ownership of a project.

json
1{
2  "name": "release_project",
3  "arguments": {
4    "project_id": "demo"
5  }
6}

Status Management

update_status

Update the status of a project.

json
1{
2  "name": "update_status",
3  "arguments": {
4    "project_id": "demo",
5    "status": "completed"
6  }
7}

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.

json
1{
2  "name": "add_note",
3  "arguments": {
4    "project_id": "demo",
5    "agent": "claude-sonnet-4",
6    "note": "Completed research phase. Found 5 relevant sources."
7  }
8}

Dependency Analysis

get_dependencies

Get dependency information for a project.

json
1{
2  "name": "get_dependencies",
3  "arguments": {
4    "project_id": "demo"
5  }
6}

Response:

json
1{
2  "success": true,
3  "data": {
4    "is_blocked": false,
5    "reasons": [],
6    "blocking_projects": [],
7    "in_cycle": false,
8    "cycle": []
9  }
10}

get_dependency_graph

Get full dependency graph for all projects.

json
1{
2  "name": "get_dependency_graph",
3  "arguments": {}
4}

Coordinator Integration

These tools require COORDINATOR_URL to be configured.

coordinator_status

Check if coordination server is available.

json
1{
2  "name": "coordinator_status",
3  "arguments": {}
4}

coordinator_claim

Claim via coordination server (prevents conflicts).

json
1{
2  "name": "coordinator_claim",
3  "arguments": {
4    "project_id": "demo",
5    "agent_name": "claude-sonnet-4",
6    "ttl_seconds": 3600
7  }
8}

coordinator_release

Release claim via coordination server.

json
1{
2  "name": "coordinator_release",
3  "arguments": {
4    "project_id": "demo"
5  }
6}

coordinator_reservations

Get all active reservations.

json
1{
2  "name": "coordinator_reservations",
3  "arguments": {}
4}

Tool Reference

Response Format

All tools return a standardized response:

json
1{
2  "success": true|false,
3  "data": { ... },      // Present on success
4  "error": "message"    // Present on failure
5}

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

1. Check ready work first - Use get_ready_work to find available projects
2. Read before claiming - Use get_project to understand the work
3. Use coordinator for parallel agents - Prevents race conditions
4. Add notes for transparency - Document your progress
5. Release when done - Don't hold claims unnecessarily
6. 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