gilbarbara/agent-hub-mcp

Agent Hub MCP

Universal AI agent coordination platform - Enable any MCP-compatible AI assistant to collaborate across projects and share knowledge seamlessly.

Why Agent Hub MCP?

The Problem: AI coding assistants work in isolation. Your Claude Code agent can't share insights with your Cursor agent. Knowledge remains trapped in individual sessions, and agents struggle to coordinate on complex, multi-service projects.

The Solution: Agent Hub MCP creates a universal coordination layer that enables any MCP-compatible AI agent to communicate, share context, and collaborate—regardless of the underlying AI platform or project location.

┌─────────────┐    ┌─────────────────┐    ┌─────────────┐
│ Claude Code │───▶│ Agent Hub MCP   │◀───│   Qwen      │
│  (Frontend) │    │     (MCP)       │    │ (Backend)   │
└─────────────┘    └─────────────────┘    └─────────────┘
                           ▲
                           │
                    ┌─────────────┐
                    │   Gemini    │
                    │ (Templates) │
                    └─────────────┘

What You Get

• 🤖 Universal Compatibility: Works with ANY MCP-compatible AI agent - no vendor lock-in
• ⚡ Minimal setup: One-line configuration, no complex installation required
• 🔄 Multi-Agent Collaboration: Agents communicate across different platforms and projects
• 🧠 Shared Intelligence: Knowledge and context flows between agents automatically
• 📋 Smart Coordination: Agents track dependencies and coordinate complex multi-service tasks
• 💾 Persistent Memory: All collaboration history preserved across sessions

Quick Start (5 minutes)

Step 1: Add Agent Hub MCP to Your AI Assistant

For Claude Code, Qwen, Gemini (JSON config):

{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "agent-hub-mcp@latest"]
    }
  }
}

For Codex (TOML config):

[mcp_servers.agent-hub]
command = "npx"
args = ["-y", "agent-hub-mcp@latest"]

Step 2: Install Custom Commands (Recommended)

Custom commands make collaboration much easier. Install them for your AI assistant:

For Claude Code:

git clone https://github.com/gilbarbara/agent-hub-mcp.git /tmp/agent-hub-mcp
mkdir -p ~/.claude/commands/hub
cp /tmp/agent-hub-mcp/commands/markdown/*.md ~/.claude/commands/hub/

For Qwen/Gemini:

git clone https://github.com/gilbarbara/agent-hub-mcp.git /tmp/agent-hub-mcp
mkdir -p ~/.qwen/commands/hub  # or ~/.gemini/commands/hub
cp /tmp/agent-hub-mcp/commands/toml/*.toml ~/.qwen/commands/hub/

This enables slash commands for:

• /hub:register (join the hub)
• /hub:sync (check for messages and workloads)
• /hub:status (view hub activity)

Step 3: Restart Your AI Assistant

Close and reopen your AI assistant completely for changes to take effect.

Step 4: Verify Installation

Register your agent:

/hub:register

You should see: ✅ Registered with Agent Hub as [your-project-name]

Without Custom Commands: Ask your AI assistant: "Register with the Agent Hub" then "Check the Hub status" Expected response: Confirmation that you're registered and connected

Troubleshooting Verification:

• ❌ No response → Check MCP server configuration and restart AI assistant
• ❌ Connection error → Verify npx -y agent-hub-mcp@latest command
• ❌ Commands not found → Ensure custom commands are installed in the correct directory

✅ Success! You should see Agent Hub MCP status information. You're ready to collaborate!

📬 Automatic Message Notifications (Optional)

Set up automatic notifications when other agents send you messages by adding a hook to your Claude Code settings:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx -y agent-hub-mcp-checker"
          }
        ]
      }
    ]
  }
}

This will automatically check for unread messages after each command and display: 📬 You have X unread messages from other agents. Type '/hub:sync' to check.

🤖 Works With Any MCP-Compatible AI Agent

Agent Hub MCP uses the Model Context Protocol (MCP) standard, making it compatible with any AI assistant that supports MCP:

✅ Verified Compatible (manually tested)

• Claude Code - Primary platform, thoroughly tested
• Qwen - Verified multi-agent collaboration.
• Gemini CLI - Confirmed working with custom commands.
• Codex - TOML configuration support

🔄 ** Likely compatible (MCP client support required)**

• Continue.dev - Has MCP client support
• Cursor - Compatible if/when MQTT/MCP plugin is enabled (check Cursor docs).
• Any custom MCP client - Follow the MCP specification.

🧪 Help Us Test

Using a different AI assistant? We'd love to verify compatibility! Open an issue with your platform details.

The key is that if your AI assistant supports MCP (Model Context Protocol), it can join the Agent Hub MCP network.

Usage

Complete Workflow Example

Here's a practical example showing frontend and backend agents collaborating on user profile features:

1. Agent Registration

# In your frontend project (React/Next.js)
/hub:register
# Registers as "frontend" with capabilities: ["ui-components", "forms", "state-management"]

# In your backend project (Node.js/Express)
/hub:register  
# Registers as "backend" with capabilities: ["api-design", "database", "validation"]

Agent Identity & Persistence:

• Agents maintain consistent IDs across restarts (no random suffixes)
• Project path determines agent identity - same path reconnects to existing agent
• Agent ID conflicts are prevented - can't use existing ID with different project path
• All messages and context are preserved when agents reconnect

2. User Request & Agent Communication

User (in frontend project): "I need endpoints to create a user profile page and a form to update user information. Can you coordinate with the backend to get the requirements?"

Frontend agent:

# Agent automatically coordinates with backend
"Hi backend agent! Working on user profile features. Need:
- GET endpoint for user profile data
- PUT endpoint for profile updates  
- Required fields and validation rules
- TypeScript types if available"

3. Backend Response

Backend agent (after syncing with hub):

# Provides complete API specification
"Here's the user profile API design:

## Endpoints
- GET /api/users/:id - Fetch user profile
- PUT /api/users/:id - Update user profile

## User Profile Model
{
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  bio?: string;
  avatar?: string;
  updatedAt: Date;
}

## Validation Rules
- firstName/lastName: 1-50 chars, required
- bio: max 500 chars, optional
- avatar: valid URL, optional

## Response Format
Success: { data: UserProfile }
Error: { error: string, field?: string }

Ready to implement. Need any specific requirements?"

4. Frontend Implementation

Frontend agent (creates plan and executes):

# Agent works autonomously to implement:
# ✅ Create UserProfile TypeScript interface
# ✅ Build profile display component
# ✅ Create profile edit form with validation
# ✅ Add API service functions
# ✅ Implement state management

"✅ User profile features implemented:
- Profile page with edit/view modes
- Form validation matching backend rules
- TypeScript types synced with your API
- Error handling for all edge cases"

Key Features Demonstrated

• 🤝 Cross-Stack Collaboration: Frontend/backend agents coordinate seamlessly
• 📋 Complete Specifications: Detailed API contracts with types and validation
• ⚡ Autonomous Implementation: Agents work independently once requirements are clear
• 💬 Natural Communication: Agents ask for clarification when needed, otherwise execute plans
• ✅ End-to-End Features: Full-stack feature development from API to UI

Note: Agents will ask users questions when they need clarification or face ambiguous requirements. Otherwise, they create detailed plans and execute autonomously.

Core Concepts

Message Types

• context - Share state/configuration
• task - Assign work to agents
• question - Request information
• completion - Report task completion
• error - Report errors

Feature Collaboration

Structured multi-agent coordination:

• Feature-based project organization
• Task delegation to domain experts
• Progress tracking through subtasks
• Context sharing within feature boundaries

Key MCP Tools

Core tools for multi-agent collaboration:

• register_agent - Register/reconnect an agent
• send_message / sync - Inter-agent communication and comprehensive status updates
• get_hub_status - Hub activity overview
• create_feature / create_task - Multi-agent project coordination

See for complete tool reference and architecture details.

🚀 How Multi-Agent Collaboration Works

Agent Hub MCP uses a feature-based collaboration system that mirrors real development workflows:

1. Feature Creation

Create multi-agent projects that span different repositories and technologies:

# Coordinator agent creates a new feature
create_feature({
  "name": "user-authentication", 
  "title": "Add User Authentication System",
  "description": "Implement login, signup, and session management across frontend and backend",
  "priority": "high",
  "estimatedAgents": ["backend-agent", "frontend-agent"]
})

2. Task Delegation

Break features into specific tasks assigned to domain experts:

create_task({
  "featureId": "user-authentication",
  "title": "Implement authentication API",
  "delegations": [
    { "agent": "backend-agent", "scope": "Create JWT auth endpoints and middleware" },
    { "agent": "frontend-agent", "scope": "Build login/signup forms and session management" }
  ]
})

3. Intelligent Work Distribution

Agents see ALL their work across features and make smart priority decisions:

# Backend agent connects and sees:
sync("backend-agent")
# Returns:
{
  "workload": {
    "activeFeatures": [
      {
        "feature": { "title": "User Authentication", "priority": "high" },
        "myDelegations": [{ "scope": "Create JWT auth endpoints", "status": "pending" }]
      },
      {
        "feature": { "title": "Performance Optimization", "priority": "critical" },
        "myDelegations": [{ "scope": "Fix database queries", "status": "in-progress" }]
    }
  ]
}

4. Context Sharing & Coordination

Agents share implementation details within feature boundaries:

# Backend completes API contract
update_subtask({
  "featureId": "user-authentication",
  "subtaskId": "auth-api-contract", 
  "status": "completed",
  "output": "JWT endpoints ready: POST /auth/login, POST /auth/signup, GET /auth/me"
})

# Frontend sees progress when checking feature data
get_feature("user-authentication") 
# Shows: subtask output with JWT endpoints info

5. Automatic Coordination

Agents unblock each other by sharing progress and outputs in real-time. The system handles:

• Priority management: Critical tasks get attention first
• Dependency tracking: Agents know what they're waiting for
• Context isolation: Each feature maintains its own scope
• Load balancing: Work distributes naturally across available agents

Advanced Setup

Custom Data Directory

To store Agent Hub MCP data in a custom location, add environment variables to your configuration:

{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "agent-hub-mcp@latest"],
      "env": {
        "AGENT_HUB_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}

For Other MCP Clients

If your AI assistant supports MCP, use these settings:

• Command: npx -y agent-hub-mcp@latest
• Protocol: Standard MCP over stdio
• Data Directory: ~/.agent-hub (or set AGENT_HUB_DATA_DIR)

Troubleshooting

Common issues:

• MCP server not connecting → Restart AI assistant
• Commands not recognized → Check custom commands installation
• Agent ID conflicts → Use unique IDs per project

📖 Need help? See for comprehensive solutions.

Requirements

• Node.js 22+
• An MCP-compatible AI assistant (Claude Code, Qwen, Gemini, etc.)

Environment Variables

Contributing

See for development setup and guidelines.

Documentation

• - Complete architecture and tool reference
• - Solutions for common issues
• - Current limitations and workarounds
• - Development setup and guidelines

License

MIT