MCP Agent Orchestration System

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

A Python implementation of a state-based agent orchestration system using the Model Context Protocol (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

- Python 3.10 or higher
- MCP Python SDK 1.2.0 or higher

# 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

# 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

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

- orchestrator.py- The main MCP server implementing the state machine
- orchestrator_client.py- Client demonstrating the orchestration flow
- requirements.txt- Dependencies for the project
- Start the orchestration server directly for testing:
- In a separate terminal, run the client to see the orchestration in action:

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

# Create or edit the configuration file code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Path may vary depending on your Windows version code %APPDATA%\Claude\claude_desktop_config.json

{ "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.
- 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

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

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
- Add the state to theAgentStateenum inorchestrator.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

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"

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

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"})

- MCP Python SDK Documentation
- Model Context Protocol Specification

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB