MCP Agent Orchestration System

A Python implementation of a state-based agent orchestration system using the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. With MCP, you can build servers that expose:

Resources: Data sources that provide information to LLMs
Tools: Functions that allow LLMs to perform actions
Prompts: Reusable templates for LLM interactions

Installation

Prerequisites

Python 3.10 or higher
MCP Python SDK 1.2.0 or higher

Setting Up Your Environment

Using uv (recommended)

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new directory for our project
uv init mcp-agents-orchestra
cd mcp-agents-orchestra

# Create virtual environment and activate it
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies
uv add "mcp[cli]" httpx

Using pip

# Create a new directory for our project
mkdir mcp-agents-orchestra
cd mcp-agents-orchestra

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Unix/macOS
venv\Scripts\activate     # On Windows

# Install dependencies
pip install "mcp[cli]" httpx

Clone or Download Project Files

Place the project files in your directory:

orchestrator.py - The main MCP server implementing the state machine
orchestrator_client.py - Client demonstrating the orchestration flow
requirements.txt - Dependencies for the project
.gitignore - Git ignore file

Project Structure

orchestrator.py - The main MCP server implementing the state machine
orchestrator_client.py - Client demonstrating the orchestration flow
requirements.txt - Dependencies for the project

Running the Orchestration System

Start the orchestration server directly for testing:

python orchestrator.py

In a separate terminal, run the client to see the orchestration in action:

python orchestrator_client.py

Integrating with Claude for Desktop

1. Install Claude for Desktop

Make sure you have Claude for Desktop installed. You can download the latest version from Anthropic's website.

2. Configure Claude for Desktop

Open your Claude for Desktop configuration file:macOS/Linux:
# Create or edit the configuration file code ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows:
# Path may vary depending on your Windows version code %APPDATA%\Claude\claude_desktop_config.json
Add the orchestrator server configuration:
{ "mcpServers": { "agent-orchestrator": { "command": "python", "args": [ "/ABSOLUTE/PATH/TO/YOUR/PROJECT/orchestrator.py" ] } } }
Replace the path with the absolute path to your orchestrator.py file.
Save the configuration file and restart Claude for Desktop.

3. Using the Orchestrator in Claude

Once configured, you can:

Open Claude for Desktop
Click on the MCP server icon in the sidebar
Select "agent-orchestrator" from the list of available servers
Start interacting with the orchestration system

Claude will be able to:

Transition between different agent states
Store and retrieve information from the knowledge base
Maintain conversation context across state transitions
Access state-specific prompts

Agent States

The orchestration system implements a state machine with the following states:

IDLE: Waiting for instructions
PLANNING: Creating a structured plan for a task
RESEARCHING: Gathering information needed for a task
EXECUTING: Carrying out planned actions
REVIEWING: Evaluating results and determining next steps
ERROR: Handling errors or unexpected situations

Customizing the System

Adding New States

Add the state to the AgentState enum in orchestrator.py
Create a prompt function for the new state
Update the transition logic in _get_available_transitions()
Add handlers for the new state in resource access functions

Creating Custom Tools

Add new tools by creating functions decorated with @mcp.tool():

@mcp.tool()
def my_custom_tool(arg1: str, arg2: int, ctx: Context) -> str:
    """Description of what this tool does
    
    Args:
        arg1: Description of arg1
        arg2: Description of arg2
    """
    # Implementation here
    return "Result"

Development and Testing

Using the MCP CLI

The MCP CLI provides tools for development and testing:

# Install MCP CLI if you haven't already
pip install "mcp[cli]"

# Test your server with the MCP Inspector
mcp dev orchestrator.py

# Install in Claude Desktop
mcp install orchestrator.py

Manual Testing with Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async with stdio_client(StdioServerParameters(command="python", args=["orchestrator.py"])) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # Test state transitions
        await session.call_tool("transition_state", arguments={"new_state": "PLANNING"})

Resources

License

This project is licensed under the MIT License - see the LICENSE file for details.

This server cannot be installed

security - not tested

license - not found

quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A state-based agent orchestration system that allows transitions between different states (IDLE, PLANNING, RESEARCHING, EXECUTING, REVIEWING, ERROR) while maintaining conversation context and providing state-specific prompts.

Related MCP Servers

MCP Orchestrator Server
mokafari
-
security
A
license
-
quality
A server for task orchestration and coordination, facilitating task management with dependencies, multi-instance collaboration, and persistent task tracking.
Last updated -
7
17
JavaScript
MIT License
ClickUp MCP Server
windalfin
-
security
A
license
-
quality
A Model Context Protocol server that enables AI agents to interact with ClickUp workspaces, allowing task creation, management, and workspace organization through natural language commands.
Last updated -
313
MIT License
Role-Specific Context MCP Server
Chris-June
-
security
F
license
-
quality
A Model Context Protocol server that enables role-based context management for AI agents, allowing users to establish specific instructions, maintain partitioned memory, and adapt tone for different agent roles in their system.
Last updated -
TypeScript
Simple Memory Extension MCP Server
gmacev
-
security
A
license
-
quality
An MCP server that extends AI agents' context window by providing tools to store, retrieve, and search memories, allowing agents to maintain history and context across long interactions.
Last updated -
5
TypeScript
MIT License

View all related MCP servers

MCP Agent Orchestration System