Agent-MCP

Agent-MCP

Advanced Tool Notice: This framework is designed for experienced AI developers who need sophisticated multi-agent orchestration capabilities. Agent-MCP requires familiarity with AI coding workflows, MCP protocols, and distributed systems concepts. We're actively working to improve documentation and ease of use. If you're new to AI-assisted development, consider starting with simpler tools and returning when you need advanced multi-agent capabilities.

Join the Community: Connect with us on Discord to get help, share experiences, and collaborate with other developers building multi-agent systems.

Multi-Agent Collaboration Protocol for coordinated AI software development.

Think Obsidian for your AI agents - a living knowledge graph where multiple AI agents collaborate through shared context, intelligent task management, and real-time visualization. Watch your codebase evolve as specialized agents work in parallel, never losing context or stepping on each other's work.

Why Multiple Agents?

Beyond the philosophical issues, traditional AI coding assistants hit practical limitations:

• Context windows overflow on large codebases
• Knowledge gets lost between conversations
• Single-threaded execution creates bottlenecks
• No specialization - one agent tries to do everything
• Constant rework from lost context and confusion

The Multi-Agent Solution

Agent-MCP transforms AI development from a single assistant to a coordinated team:

Real-time visualization shows your AI team at work - purple nodes represent context entries, blue nodes are agents, and connections show active collaborations. It's like having a mission control center for your development team.

Core Capabilities

Parallel Execution
Multiple specialized agents work simultaneously on different parts of your codebase. Backend agents handle APIs while frontend agents build UI components, all coordinated through shared memory.

Persistent Knowledge Graph

Your project's entire context lives in a searchable, persistent memory bank. Agents query this shared knowledge to understand requirements, architectural decisions, and implementation details. Nothing gets lost between sessions.

Intelligent Task Management

Monitor every agent's status, assigned tasks, and recent activity. The system automatically manages task dependencies, prevents conflicts, and ensures work flows smoothly from planning to implementation.

Quick Start

Python Implementation (Recommended)

…

Node.js/TypeScript Implementation (Alternative)

# Clone and setup
git clone https://github.com/rinadelph/Agent-MCP.git
cd Agent-MCP/agent-mcp-node

# Install dependencies
npm install

# Configure environment
cp .env.example .env  # Add your OpenAI API key

# Start the server
npm run server

# Or use the built version
npm run build
npm start

# Or install globally
npm install -g agent-mcp-node
agent-mcp --port 8080 --project-dir path-to-directory

MCP Integration Guide

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely connect to external data sources and tools. Agent-MCP leverages MCP to provide seamless integration with various development tools and services.

Running Agent-MCP as an MCP Server

Agent-MCP can function as an MCP server, exposing its multi-agent capabilities to MCP-compatible clients like Claude Desktop, Cline, and other AI coding assistants.

Quick MCP Setup

# 1. Install Agent-MCP
uv venv
uv install

# 2. Start the MCP server
uv run -m agent_mcp.cli --port 8080

# 3. Configure your MCP client to connect to:
# HTTP: http://localhost:8000/mcp
# WebSocket: ws://localhost:8000/mcp/ws

MCP Server Configuration

Create an MCP configuration file (mcp_config.json):

…

Using Agent-MCP with Claude Desktop

1. Add to Claude Desktop Config:

   Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

   json复制

   {
     "mcpServers": {
       "agent-mcp": {
         "command": "uv",
         "args": ["run", "-m", "agent_mcp.cli", "--port", "8080"],
         "env": {
           "OPENAI_API_KEY": "your-openai-api-key"
         }
       }
     }
   }

2. Restart Claude Desktop to load the MCP server

3. Verify Connection: Claude should show " agent-mcp" in the conversation

MCP Tools Available

Once connected, you can use these MCP tools directly in Claude:

Agent Management

• create_agent - Spawn specialized agents (backend, frontend, testing, etc.)
• list_agents - View all active agents and their status
• terminate_agent - Safely shut down agents

Task Orchestration

• assign_task - Delegate work to specific agents
• view_tasks - Monitor task progress and dependencies
• update_task_status - Track completion and blockers

Knowledge Management

• ask_project_rag - Query the persistent knowledge graph
• update_project_context - Add architectural decisions and patterns
• view_project_context - Access stored project information

Communication

• send_agent_message - Direct messaging between agents
• broadcast_message - Send updates to all agents
• request_assistance - Escalate complex issues

Advanced MCP Configuration

Custom Transport Options:

# HTTP with custom port
uv run -m agent_mcp.cli --port 8080

# WebSocket with authentication
uv run -m agent_mcp.cli --port 8080 --auth-token your-secret-token

# Unix socket (Linux/macOS)
uv run -m agent_mcp.cli --port 8080

Environment Variables:

export AGENT_MCP_HOST=0.0.0.0          # Server host
export AGENT_MCP_PORT=8000              # Server port  
export AGENT_MCP_LOG_LEVEL=INFO         # Logging level
export AGENT_MCP_PROJECT_DIR=/your/project  # Default project directory
export AGENT_MCP_MAX_AGENTS=10          # Maximum concurrent agents

MCP Client Examples

Python Client

…

JavaScript Client

import { MCPClient } from '@modelcontextprotocol/client';

const client = new MCPClient('http://localhost:8000/mcp');

async function createAgent() {
  await client.connect();
  
  const agent = await client.callTool('create_agent', {
    role: 'frontend',
    specialization: 'React components'
  });
  
  console.log('Created agent:', agent.agent_id);
  
  await client.disconnect();
}

createAgent().catch(console.error);

Troubleshooting MCP Connection

Connection Issues:

# Check if MCP server is running
curl http://localhost:8000/mcp/health

# Verify WebSocket connection
wscat -c ws://localhost:8000/mcp/ws

# Check server logs
uv run -m agent_mcp.cli --port 8080 --log-level DEBUG

Common Issues:

• Port conflicts: Change port with --port flag
• Permission errors: Ensure OpenAI API key is set
• Client timeout: Increase timeout in client configuration
• Agent limit reached: Check active agent count with list_agents

Integration Examples

VS Code with MCP: Use the MCP extension to integrate Agent-MCP directly into your editor workflow.

Terminal Usage:

# Quick task assignment via curl
curl -X POST http://localhost:8000/mcp/tools/assign_task \
  -H "Content-Type: application/json" \
  -d '{"task": "Add error handling to API endpoints", "agent_role": "backend"}'

CI/CD Integration:

# GitHub Actions example
- name: Run Agent-MCP Code Review
  run: |
    uv run -m agent_mcp.cli --port 8080 --daemon
    curl -X POST localhost:8000/mcp/tools/assign_task \
      -d '{"task": "Review PR for security issues", "agent_role": "security"}'

How It Works: Breaking Complexity into Simple Steps

graph LR
    A[Step 1] --> B[Step 2] --> C[Step 3] --> D[Step 4] --> E[Done!]
    style A fill:#4ecdc4,color:#fff
    style E fill:#ff6b6b,color:#fff

Every task can be broken down into linear steps. This is the core insight that makes Agent-MCP powerful.

The Problem with Complex Tasks

graph TD
    A["Build User Authentication"] -->|Single Agent Tries Everything| B{???}
    B --> C[Database?]
    B --> D[API?]
    B --> E[Frontend?]
    B --> F[Security?]
    B --> G[Tests?]
    C -.->|Confused| H[Incomplete Implementation]
    D -.->|Overwhelmed| H
    E -.->|Context Lost| H
    F -.->|Assumptions| H
    G -.->|Forgotten| H
    style A fill:#ff6b6b,color:#fff
    style H fill:#666,color:#fff

The Agent-MCP Solution

graph TD
    A["Build User Authentication"] -->|Break Down| B[Linear Tasks]
    B --> C["Agent 1: Database"]
    B --> D["Agent 2: API"]
    B --> E["Agent 3: Frontend"]
    
    C --> C1[Create users table]
    C1 --> C2[Add indexes]
    C2 --> C3[Create sessions table]
    
    D --> D1[POST /register]
    D1 --> D2[POST /login]
    D2 --> D3[POST /logout]
    
    E --> E1[Login Form]
    E1 --> E2[Register Form]
    E2 --> E3[Auth Context]
    
    C3 --> F[Working System]
    D3 --> F
    E3 --> F
    
    style A fill:#4ecdc4,color:#fff
    style F fill:#4ecdc4,color:#fff

Each agent focuses on their linear chain. No confusion. No context pollution. Just clear, deterministic progress.

The 5-Step Workflow

1. Initialize Admin Agent

You are the admin agent.
Admin Token: "your_admin_token_from_server"

Your role is to:
- Coordinate all development work
- Create and manage worker agents
- Maintain project context
- Assign tasks based on agent specializations

2. Load Your Project Blueprint (MCD)

Add this MCD (Main Context Document) to project context:

[paste your MCD here - see docs/mcd-guide.md for structure]

Store every detail in the knowledge graph. This becomes the single source of truth for all agents.

The MCD (Main Context Document) is your project's comprehensive blueprint - think of it as writing the book of your application before building it. It includes:

• Technical architecture and design decisions
• Database schemas and API specifications
• UI component hierarchies and workflows
• Task breakdowns with clear dependencies

See our MCD Guide for detailed examples and templates.

3. Deploy Your Agent Team

Create specialized agents for parallel development:

- backend-worker: API endpoints, database operations, business logic
- frontend-worker: UI components, state management, user interactions
- integration-worker: API connections, data flow, system integration
- test-worker: Unit tests, integration tests, validation
- devops-worker: Deployment, CI/CD, infrastructure

Each agent specializes in their domain, leading to higher quality implementations and faster development.

4. Initialize and Deploy Workers

# In new window for each worker:
You are [worker-name] agent.
Your Admin Token: "worker_token_from_admin"

Query the project knowledge graph to understand:
1. Overall system architecture
2. Your specific responsibilities
3. Integration points with other components
4. Coding standards and patterns to follow
5. Current implementation status

Begin implementation following the established patterns.

AUTO --worker --memory

Important: Setting Agent Modes

Agent modes (like --worker, --memory, --playwright) are not just flags - they activate specific behavioral patterns. In Claude Code, you can make these persistent by:

1. Copy the mode instructions to your clipboard
2. Type # to open Claude's memory feature
3. Paste the instructions for persistent behavior

Example for Claude Code memory:

# When I use "AUTO --worker --memory", follow these patterns:
- Always check file status before editing
- Query project RAG for context before implementing
- Document all changes in task notes
- Work on one file at a time, completing it before moving on
- Update task status after each completion

This ensures consistent behavior across your entire session without