# Agent Hub MCP
[](https://badge.fury.io/js/agent-hub-mcp) [](https://github.com/gilbarbara/agent-hub-mcp/actions/workflows/quality-assurance.yml) [](https://sonarcloud.io/summary/new_code?id=gilbarbara_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):
```json
{
"mcpServers": {
"agent-hub": {
"command": "npx",
"args": ["-y", "agent-hub-mcp@latest"]
}
}
}
```
For **Codex** (TOML config):
```toml
[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:**
```bash
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:**
```bash
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:**
```bash
/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:
```json
{
"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**
```bash
# 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**:
```bash
# 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):
```bash
# 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):
```bash
# 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 [System Overview](./docs/SYSTEM-OVERVIEW.md) 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:
```bash
# 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:
```bash
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:
```bash
# 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:
```bash
# 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:
```json
{
"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 [Troubleshooting Guide](./docs/TROUBLESHOOTING.md) for comprehensive solutions.
## Requirements
- Node.js 22+
- An MCP-compatible AI assistant (Claude Code, Qwen, Gemini, etc.)
## Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_HUB_DATA_DIR` | `~/.agent-hub` | Storage directory |
## Contributing
See [Contributing Guide](./docs/CONTRIBUTING.md) for development setup and guidelines.
## Documentation
- **[System Overview](./docs/SYSTEM-OVERVIEW.md)** - Complete architecture and tool reference
- **[Troubleshooting](./docs/TROUBLESHOOTING.md)** - Solutions for common issues
- **[Known Issues](./docs/KNOWN-ISSUES.md)** - Current limitations and workarounds
- **[Contributing](./docs/CONTRIBUTING.md)** - Development setup and guidelines
## License
MIT
