Implements environment variable management through .env files for configuration of API keys and system settings
Supports project management through Git, with cloning repositories as part of the setup process
Enables project initialization from GitHub repositories as part of the setup workflow
Provides integration with OpenAI's API, requiring an API key for agent operations and model usage in the multi-agent system
Supports development of React components through specialized worker agents with frontend/React capabilities
Uses SQLite for storing system state and token usage data, with querying capabilities for resource monitoring
Agent MCP
A framework for creating multi-agent systems using the MCP (Model Context Protocol) for coordinated, efficient AI collaboration.
Quick Start Guide
Note: I recommend using MultipleCursor to launch different chat windows on the same codebase as shown in the screenshot above.
1. Setup Environment
- Clone repo & copy
.env.example
to.env
- Add your OpenAI API key to
.env
- Install with
uv venv && uv pip install -e .
2. Start MCP Server
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:
- Install a SQLite viewer extension in your code editor
- Open the database at
/path/to/your/project/.agent/mcp_state.db
- Check the
project_context
table for the admin token
3. Create Main Context Document (MCD)
- 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
4. Launch Admin Agent
- Open your AI coding assistant (Claude Code, Cursor, etc.) in your project folder
- Copy the admin token you found in step 2
- Ask the AI to "Initialize as an admin agent with this token: [your-token]"
- Tell the admin agent to add your MCD to the project context with:
5. Create and Manage Worker Agents Through Admin
- Ask your admin agent to create a worker agent:
- Open a new window/session in your AI assistant (same codebase)
- Initialize the worker with this exact prompt:
- The worker will automatically find its assigned tasks and start working
Follow the detailed instructions below for more information.
Features
- 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
Project Planning with the Main Context Document (MCD)
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:
- It enables agents to understand the overall system before working on individual components
- It allows linear, coordinated building (like constructing a house from blueprints)
- It reduces token usage by providing structured, relevant context
- 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.
Installation
Prerequisites
- Python 3.8+
- uv (recommended for faster package installation)
Setup
- Clone the repository:
- Set up environment variables by copying the example file:
- Edit the
.env
file and add your OpenAI API key: - Install using uv:Or with pip:
Multi-Agent Workflow
Workflow Overview
- Begin with Deep Research: Before coding, use AI to help create a comprehensive Main Context Document (MCD)
- Start the Infrastructure: Launch the MCP server and locate your admin token in the database
- Admin Agent Setup: Initialize your admin agent with the token and docs/INSTRUCTIONS.md
- Worker Creation: Admin creates specialized workers for different aspects of your project
- Task Assignment: Admin breaks down the MCD into discrete tasks and assigns to workers
- Parallel Development: Workers execute tasks while sharing context through the MCP
- Context Preservation: All agents store their knowledge in the central database
Development Loop
Architecture Overview
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.)
Agent Setup and Operation
1. Starting the MCP Server
Options:
--port
: Port to run the server on (default: 8080)--project-dir
: Base directory for the project
2. Understanding MCP Tokens
The MCP system uses two types of tokens for authentication:
Admin Token:
- After starting the server, an admin token is automatically generated
- This token is stored in the
.agent/mcp_state.db
SQLite database - Install a SQLite viewer extension for VS Code or another SQLite tool
- Open the database and check the
project_context
table - Look for the admin token entry
- The admin token should ONLY be used with the admin agent
Worker Tokens:
- When the admin agent creates a worker agent, a specific worker token is generated
- The admin agent will provide this worker token when asked to create a worker
- Each worker has its own unique token with specific permissions
- 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.
3. Agent Workflow (IMPORTANT)
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:
Admin Agent - Create by telling your AI assistant:
Worker Agents - Create through the admin agent with:
- Tell the admin agent: "Create a worker agent with ID 'frontend-worker' to implement the login page"
- The admin will provide a specific worker token for this agent
- Open a new AI assistant window/session
- 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
4. Initializing Worker Agents (Copy/Paste This)
After your admin agent creates a worker, open a new AI assistant window and initialize the worker with this EXACT prompt:
Make these two replacements:
- Replace
[agent_id]
with the worker ID you told the admin to create (e.g., "frontend-worker") - 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:
- Check for tasks assigned to its ID
- Ask the RAG system about the project context
- Start working on its tasks autonomously
- 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.
Dashboard and Terminal UI
Dashboard (Visualization)
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.
Multiple Agent Sessions: Visual Guide
For complex projects, you'll have multiple chat sessions open at once:
How this works:
- One window/session for your admin agent
- Separate windows/sessions for each worker agent
- Admin uses admin token, workers use their specific worker tokens
- Each worker has a UNIQUE agent ID and token
Example setup with 3 agents:
Window | Agent Type | Agent ID | Token Type |
---|---|---|---|
1 | Admin | "admin" | Admin token |
2 | Worker | "frontend-worker" | Frontend worker token |
3 | Worker | "backend-worker" | Backend worker token |
You can use Claude Code, RooCode, or MultipleCursor to manage multiple windows/sessions working on the same codebase.
Complete Example Workflow
Here's a step-by-step example of how to use Agent MCP from start to finish:
Step 1: Create Your Project
Step 2: Install Agent MCP
Step 3: Create Your MCD
Step 4: Start MCP Server
Step 5: Find Admin Token
- Install SQLite Viewer in your code editor
- Open
.agent/mcp_state.db
- Look for the token in
project_context
table
Step 6: Initialize Admin Agent
- Open your AI assistant (Claude Code, Cursor, etc.)
- Tell it:
Step 7: Create Worker Agent
- Tell the admin agent:
- The admin agent will provide you with a worker token for this new agent
Step 8: Initialize Worker Agent
- Open a new AI assistant window
- Tell it:
The worker will now automatically start working on its assigned tasks!
Token System and Resource Management
Understanding Tokens
Tokens serve multiple purposes in the MCP system:
- Authentication Tokens: Used for agent identification and admin access
- RAG Tokens: Used for embedding and retrieving context from the knowledge base
- OpenAI Tokens: Consumed during agent operations (model usage)
Token Management
To monitor and manage token usage:
- Install SQLite Viewer plugin or use the command line:
- Query token usage:
- Monitor in the dashboard under the "Resources" tab
Resource Optimization
For large projects:
- Use specialized agents with focused capabilities to reduce context size
- Break tasks into smaller units with clear dependencies
- Utilize the RAG system for efficient context retrieval
- Store shared information in the project context rather than repeating in messages
Project RAG and Knowledge Base (Central Memory System)
Watch the tutorial above: See exactly how to add your MCD to the central memory system
How the Memory System Works
- The MCP server maintains a central database for all project context
- When you start the server, it creates a
.agent
folder in your project directory - Your admin agent adds your MCD to this database when you initialize it
- Worker agents automatically query this database to understand their tasks
- All implementation details are stored back in this database for other agents to access
Setting Up the Project RAG
The Retrieval-Augmented Generation (RAG) system allows agents to access relevant project knowledge efficiently:
- Index project files:
- Add documentation to the knowledge base:
Using RAG in Agent Workflows
Agents can query the knowledge base using:
Community
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.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Multi-Agent Collaboration Protocol server that enables coordinated AI collaboration through task management, context sharing, and agent interaction visualization.
Related MCP Servers
- -securityAlicense-qualityA Model Context Protocol server that enables collaborative debates between multiple AI agents, allowing them to discuss and reach consensus on user prompts.Last updated -TypeScriptMIT License
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants to interact with Confluence content, supporting operations like retrieving, searching, creating, and updating pages and spaces.Last updated -93TypeScriptMIT License
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -16TypeScript
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to interact with GitLab repositories, allowing tasks like managing merge requests, searching projects, and creating comments through RESTful API integration.Last updated -672TypeScript