Agent-MCP: Building Multi-Agent Systems with the Model Context Protocol

Agent-MCP is a multi-agent framework built on the Model Context Protocol (MCP). It utilizes a standardized communication protocol to enable seamless coordination between multiple AI agents.

Two-layer collaboration. The framework organizes agents into two distinct roles: the Admin Agent and Worker Agents. The Admin Agent manages global task scheduling and maintains context consistency across the project. Worker Agents focus on specific execution tasks, such as frontend development, backend API construction, or data processing.

Shared context. A central database serves as the repository for project context, including architectural documentation and task specifics. Agents query this shared knowledge base dynamically, which eliminates redundant messaging and significantly reduces token consumption.

Visual tools. The integrated dashboard provides real-time analytics on agent interactions and task progression. Additionally, a TUI (Terminal User Interface) and CLI are available for streamlined token management and task tracking.

Quick Start

Follow these three steps to get Agent-MCP running: set up the environment, launch the service, and configure your agents.

(1) Environment setup

Clone the repository:

git clone https://github.com/rinadelph/Agent-MCP.git
cd Agent-MCP

Copy the example environment file and insert your OpenAI API key:

cp .env.example .env
# Edit .env and add your OpenAI API key
OPENAI_API_KEY=your_api_key_here

Install dependencies. We recommend using uv to manage your virtual environment and installation:

uv venv
uv pip install -e .

If you prefer using standard pip:

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
pip install -e .

(2) Start the MCP service

Execute the following command, specifying your desired port and project directory:

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

Important: Upon startup, the service generates an .agent folder within your project directory. This folder contains an SQLite database named mcp_state.db.

To proceed, access this database using an SQLite viewer (such as the SQLite extension for VS Code). Locate the project_context table and copy the value from the admin_token field.

(3) Initialize agents and assign tasks

Configure the Admin Agent.

Open your preferred AI coding assistant (e.g., Claude Code, Cursor) and input the following:

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

Note: Before running this command, ensure you have created a Master Context Document (MCD.md) in your project root. This document should outline your system architecture, API designs, and data models. A template is available in the MCD-EXAMPLE folder of the repository.

Create a Worker Agent.

Instruct the Admin Agent to generate a new worker:

Create a worker agent with ID "backend-worker" to implement the user authentication API.

The Admin Agent will provide a worker token. Open a new AI assistant window and initialize the worker as follows:

You are backend-worker agent, your Worker Token: "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

Replace the placeholder with the actual token. The worker will then retrieve its specific task context from the central database and begin execution.

Core Components & Best Practices

The MCD as the Single Source of Truth. High-quality MCD documentation is essential for agent efficiency. Your MCD should include:

• System Architecture Diagram: Illustrate how components like the frontend, backend, and database interact.
• Feature Requirements: Deconstruct requirements into specific modules (e.g., a "User Module" covering registration, login, and permissions).
• Task Breakdown Table: Convert requirements into a clear execution roadmap.

Token System & Resource Management

• Admin Token: Reserved for the Admin Agent. It grants permissions to create workers and modify the project context.
• Worker Token: Generated uniquely for each worker. It restricts the agent's scope to its assigned tasks. These tokens are issued by the Admin Agent.

Monitor token usage via SQLite or the dashboard:

sqlite3 .agent/mcp_state.db "SELECT * FROM token_usage;"

Optimization Tip: Deconstruct complex projects into granular tasks. Utilize the RAG system to retrieve specific context only when needed, avoiding the transmission of redundant information.

Visualization & Interaction Tools

• Dashboard: Access http://localhost:8080 to view the agent network topology, track progress via Gantt charts, and monitor live data.
• TUI/CLI: Manage multiple projects directly from your terminal:

# List all current tasks (CLI)
./scripts/mcp --token your_admin_token task list

# Launch the interactive terminal UI (TUI)
python -m mcp_template_terminal_ui.tui

Example Workflow

Below is the standard workflow for building a full-stack application with Agent-MCP:

1. Project Initialization: Create a directory, initialize Git, and draft an MCD document defining the architecture.
2. Service Launch: Start the MCP service and retrieve the admin token from the SQLite database.
3. Admin Deployment: Initialize the Admin Agent and load the MCD document to establish the project context.
4. Worker Assignment: Command the Admin Agent to create specialized workers (e.g., one for frontend UI and one for backend APIs).
5. Parallel Development: Agents synchronize through the central database. For instance, once the frontend agent defines a UI component, the backend agent can immediately query that definition to begin integration.

Advanced Features

RAG System Integration. Use the rag_indexer tool to ingest project files—such as API documentation or design assets—into the central knowledge base. Agents can then perform natural language queries:

# Index project files
python -m mcp_template.rag_indexer --project-dir /path/to/project

# Query the knowledge base programmatically
response = await client.ask_project_rag("What is the schema for the user table?")

Multi-agent Session Management. Tools like MultipleCursor can be used to manage multiple AI assistant windows simultaneously. Running one agent instance per window enables true parallel development and execution.