A framework for creating multi-agent systems using the MCP (Model Context Protocol) for coordinated, efficient AI collaboration.

Note: I recommend using MultipleCursor to launch different chat windows on the same codebase as shown in the screenshot above.

• Clone repo & copy .env.example to .env
• Add your OpenAI API key to .env
• Install with uv venv && uv pip install -e .

uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project

IMPORTANT: When the server starts, it will create a database in your project's .agent folder. Your admin token is stored in this database. To find it:

1. Install a SQLite viewer extension in your code editor
2. Open the database at /path/to/your/project/.agent/mcp_state.db
3. Check the project_context table for the admin token

• Create a detailed MCD.md file in your project with architecture, API routes, data models, etc.
• This can be a single file or multiple files (for complex projects)
• See the MCD-EXAMPLE folder for templates

1. Open your AI coding assistant (Claude Code, Cursor, etc.) in your project folder
2. Copy the admin token you found in step 2
3. Ask the AI to "Initialize as an admin agent with this token: [your-token]"
4. Tell the admin agent to add your MCD to the project context with:

   Please add the MCD.md file to the project context. Don't summarize it.
   

1. Ask your admin agent to create a worker agent:

   Create a worker agent with ID "frontend-worker" to implement the login page.
   

2. Open a new window/session in your AI assistant (same codebase)
3. Initialize the worker with this exact prompt:

   You are [worker-id] agent, your Admin Token: "[admin-token]"
   
   Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea.
   
   AUTO --worker --memory
   

4. The worker will automatically find its assigned tasks and start working

Follow the detailed instructions below for more information.

• Multi-agent collaboration framework
• Task management and coordination
• Context and knowledge sharing between agents
• Graph visualization of agent interactions
• Support for embedding and RAG capabilities
• Interactive dashboard for visualizing tasks, agents and context.

Watch the video tutorial: How to add MCD context to Agent MCP

Before starting development, it's essential to use deep research to create a Main Context Document (MCD) - the single source of truth for your application. This document provides a granular plan detailing:

• System architecture and component relationships
• UI/UX design for all screens and components
• API routes and endpoints
• Data structures and models
• Implementation units and tasks
• Dependencies and technology stack

The MCD is critical because:

1. It enables agents to understand the overall system before working on individual components
2. It allows linear, coordinated building (like constructing a house from blueprints)
3. It reduces token usage by providing structured, relevant context
4. It prevents conflicting implementations between agents

Review the MCD.md file in this repository to understand the structure and level of detail required. The MCD should contain:

• Overview and goals
• Context and architecture diagrams
• Functional requirements
• Design specifications (UI/UX, API, data models)
• Implementation details
• Task breakdown for agents

With a comprehensive MCD, agents can implement your application part-by-part with a clear understanding of how each piece fits into the whole.

• Python 3.8+
• uv (recommended for faster package installation)

1. Clone the repository:

   git clone https://github.com/your-username/agent-mcp.git
   cd agent-mcp

2. Set up environment variables by copying the example file:

   cp .env.example .env

3. Edit the .env file and add your OpenAI API key:

   OPENAI_API_KEY=your_openai_api_key_here
   

4. Install using uv:

   uv venv
   uv pip install -e .

   Or with pip:

   pip install -e .

1. Begin with Deep Research: Before coding, use AI to help create a comprehensive Main Context Document (MCD)
2. Start the Infrastructure: Launch the MCP server and locate your admin token in the database
3. Admin Agent Setup: Initialize your admin agent with the token and docs/INSTRUCTIONS.md
4. Worker Creation: Admin creates specialized workers for different aspects of your project
5. Task Assignment: Admin breaks down the MCD into discrete tasks and assigns to workers
6. Parallel Development: Workers execute tasks while sharing context through the MCP
7. Context Preservation: All agents store their knowledge in the central database

graph TD
    A[Research & MCD Creation] --> B[MCP Server Setup]
    B --> C[Admin Agent Initialization]
    C --> D[Worker Agent Creation]
    D --> E[Task Assignment]
    E --> F[Parallel Development]
    F --> G[Knowledge Storage in MCP DB]
    G --> E

The MCP system uses a hierarchical structure with:

• Admin Agent: Coordinates other agents, assigns tasks, and maintains overall project direction
• Worker Agents: Specialized agents that execute specific tasks (frontend, backend, data modeling, etc.)

uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project

Options:

• --port: Port to run the server on (default: 8080)
• --project-dir: Base directory for the project

The MCP system uses two types of tokens for authentication:

Admin Token:

1. After starting the server, an admin token is automatically generated
2. This token is stored in the .agent/mcp_state.db SQLite database
3. Install a SQLite viewer extension for VS Code or another SQLite tool
4. Open the database and check the project_context table
5. Look for the admin token entry
6. The admin token should ONLY be used with the admin agent

Worker Tokens:

1. When the admin agent creates a worker agent, a specific worker token is generated
2. The admin agent will provide this worker token when asked to create a worker
3. Each worker has its own unique token with specific permissions
4. Worker tokens are also stored in the .agent/mcp_state.db database

IMPORTANT: Do NOT use the admin token for worker agents. Always use the specific worker token provided by the admin agent when it creates the worker.

Note: All agents are created and managed through chat with your AI assistant - you do NOT use command line tools to create agents.

MCP Server - This is the ONLY component you start with a command:

uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project

Admin Agent - Create by telling your AI assistant:

Initialize as an admin agent with this token: [paste-admin-token-here]
Please add the MCD.md file to the project context. Don't summarize it.

Worker Agents - Create through the admin agent with:

1. Tell the admin agent: "Create a worker agent with ID 'frontend-worker' to implement the login page"
2. The admin will provide a specific worker token for this agent
3. Open a new AI assistant window/session
4. Initialize with the worker token and the worker prompt from section 4 below

The Dashboard (http://localhost:8080):

• This is just for visualization - you don't create agents here
• All actual work happens through your AI assistant chat windows
• The dashboard shows relationships between agents and tasks

After your admin agent creates a worker, open a new AI assistant window and initialize the worker with this EXACT prompt:

You are [agent_id] agent, your Worker Token: "your_worker_token_here"

Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea.

AUTO --worker --memory

Make these two replacements:

1. Replace [agent_id] with the worker ID you told the admin to create (e.g., "frontend-worker")
2. Replace your_worker_token_here with the specific worker token that the admin agent provided when creating this worker (NOT the admin token)

After initialization, the worker will:

1. Check for tasks assigned to its ID
2. Ask the RAG system about the project context
3. Start working on its tasks autonomously
4. Store implementation details in the shared memory system

For best results, also copy the content of docs/INSTRUCTIONS.md and paste it before the AUTO command.

Access the dashboard at http://localhost:8080 to visualize what's happening in your multi-agent system:

• Monitor agent activities in real-time
• View task status and dependencies
• Observe agent relationships and coordination
• Track file operations and context sharing

Important: The dashboard is only for visualization - you don't create or manage agents here. All agent creation and task assignment happens through your AI assistant chat.

For complex projects, you'll have multiple chat sessions open at once:

How this works:

1. One window/session for your admin agent
2. Separate windows/sessions for each worker agent
3. Admin uses admin token, workers use their specific worker tokens
4. Each worker has a UNIQUE agent ID and token

Example setup with 3 agents:

You can use Claude Code, RooCode, or MultipleCursor to manage multiple windows/sessions working on the same codebase.

Here's a step-by-step example of how to use Agent MCP from start to finish:

mkdir -p my-project
cd my-project
git init
# Create initial project files

git clone https://github.com/rinadelph/Agent-MCP.git mcp
cd mcp
uv venv
uv pip install -e .
cd ..

# Create your MCD file (with help from your AI assistant)
touch MCD.md

uv run -m mcp_template.main --port 8080 --project-dir $(pwd)

1. Install SQLite Viewer in your code editor
2. Open .agent/mcp_state.db
3. Look for the token in project_context table

1. Open your AI assistant (Claude Code, Cursor, etc.)
2. Tell it:

Initialize as an admin agent with this token: [paste-token-here]
Please add the MCD.md file to the project context. Don't summarize it.

1. Tell the admin agent:

Create a worker agent with ID "frontend-worker" to implement the login page component.

2. The admin agent will provide you with a worker token for this new agent

1. Open a new AI assistant window
2. Tell it:

You are frontend-worker agent, your Worker Token: "[paste-worker-token-here]"

Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea.

AUTO --worker --memory

The worker will now automatically start working on its assigned tasks!

Tokens serve multiple purposes in the MCP system:

1. Authentication Tokens: Used for agent identification and admin access
2. RAG Tokens: Used for embedding and retrieving context from the knowledge base
3. OpenAI Tokens: Consumed during agent operations (model usage)

To monitor and manage token usage:

1. Install SQLite Viewer plugin or use the command line:

   sqlite3 /path/to/project/.agent/mcp_state.db

2. Query token usage:

   SELECT * FROM token_usage;

3. Monitor in the dashboard under the "Resources" tab

For large projects:

1. Use specialized agents with focused capabilities to reduce context size
2. Break tasks into smaller units with clear dependencies
3. Utilize the RAG system for efficient context retrieval
4. Store shared information in the project context rather than repeating in messages

Watch the tutorial above: See exactly how to add your MCD to the central memory system

1. The MCP server maintains a central database for all project context
2. When you start the server, it creates a .agent folder in your project directory
3. Your admin agent adds your MCD to this database when you initialize it
4. Worker agents automatically query this database to understand their tasks
5. All implementation details are stored back in this database for other agents to access

The Retrieval-Augmented Generation (RAG) system allows agents to access relevant project knowledge efficiently:

1. Index project files:

   python -m mcp_template.rag_indexer --project-dir /path/to/project

2. Add documentation to the knowledge base:

   python -m mcp_template.rag_indexer --add-doc /path/to/document.md

Agents can query the knowledge base using:

response = await client.ask_project_rag("How does the authentication system work?")

This returns relevant context without loading entire files, saving tokens and improving response quality.

For optimal performance, follow these guidelines:

1. Task Granularity: Break down large tasks into atomic units with clear inputs/outputs
2. Dependency Tracking: Explicitly define task dependencies in assignment
3. Capability Matching: Assign tasks to agents with relevant capabilities
4. Progress Monitoring: Use explicit status updates to track task progress
5. Context Sharing: Provide necessary context at assignment time to reduce later lookups

Example task assignment from admin to worker:

@worker1 Please implement the login form component based on the MCD section 6.1. 
Dependencies: None
Artifacts: src/components/LoginForm.tsx
Context: Uses FormKit, requires email validation

When creating a new worker agent:

1. Tell your admin agent: "Create a new agent with ID 'frontend-worker' and assign it to implement the login page based on the MCD."
2. Open a new window/session and initialize the worker agent with the AUTO prompt described earlier
3. Make sure to include the admin token so the worker can access its assigned tasks

• main.py: MCP server implementation
• mcp_client.py: Client library for connecting agents to MCP
• dashboard_api.py: API endpoints for visualization
• rag_agent_test.py: Example of a RAG-capable agent
• docs/INSTRUCTIONS.md: Operational guidelines for agents

• OPENAI_API_KEY: Your OpenAI API key
• MCP_SERVER_URL: URL of the MCP server
• MCP_ADMIN_TOKEN: (Optional) Admin token for direct access
• MCP_PROJECT_DIR: Path to the project directory

MIT License

Join our Discord community to discuss Agent MCP, share your projects, get help, and connect with other developers building with AI tools. We're a growing community focused on pushing the boundaries of what's possible with multi-agent systems and AI collaboration.