Implements an MCP server in Python that exposes resources, tools, and prompts for LLM interactions, utilizing Python's capabilities for building the state machine orchestration system
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)
Using pip
Clone or Download Project Files
Place the project files in your directory:
orchestrator.py
- The main MCP server implementing the state machineorchestrator_client.py
- Client demonstrating the orchestration flowrequirements.txt
- Dependencies for the project.gitignore
- Git ignore file
Project Structure
orchestrator.py
- The main MCP server implementing the state machineorchestrator_client.py
- Client demonstrating the orchestration flowrequirements.txt
- Dependencies for the project
Running the Orchestration System
Start the orchestration server directly for testing:
In a separate terminal, run the client to see the orchestration in action:
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.jsonWindows:
# Path may vary depending on your Windows version code %APPDATA%\Claude\claude_desktop_config.jsonAdd 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 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
Creating Custom Tools
Add new tools by creating functions decorated with @mcp.tool()
:
Development and Testing
Using the MCP CLI
The MCP CLI provides tools for development and testing:
Manual Testing with Python
Resources
License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
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
- -securityAlicense-qualityA lightweight framework for building and orchestrating AI agents through the Model Context Protocol, enabling users to create scalable multi-agent systems using only configuration files.Last updated -MIT License
- -securityFlicense-qualityAn agentic AI system that orchestrates multiple specialized AI tools to perform business analytics and knowledge retrieval, allowing users to analyze data and access business information through natural language queries.Last updated -3
- -securityFlicense-qualityA master control platform that orchestrates intelligent agents with a plug-and-play architecture, allowing users to manage and coordinate multiple AI agents through a unified system.Last updated -
- -securityFlicense-qualityA master control program that orchestrates intelligent agents with a plug-and-play architecture, enabling seamless coordination and management of AI agent workflows.Last updated -