Content
# Claude Code MCP - Agent Orchestration Platform
## Overview
A sophisticated **FastMCP Python server** that orchestrates multiple Claude Code agents across iTerm2 sessions, providing centralized management and inter-agent communication through task-based workflows.
## Architecture
**Agent Orchestration Platform** with:
- **iTerm2 Tab-Based Sessions**: No window complexity, pure tab management
- **Persistent Agent State**: Survives iTerm restarts with state recovery
- **Codebase-Linked Sessions**: Sessions tied to specific root filepaths
- **Maximum Security Isolation**: Process-level separation between agents
- **Task-Based Inter-Agent Communication**: ADDER+ workflow coordination
- **System Prompt Injection**: Automatic Agent_# naming and prompt prepending
## Core MCP Tools
| Tool | Purpose | Security Level |
|------|---------|----------------|
| `create_agent` | Creates new Claude Code agent instance | HIGH |
| `delete_agent` | Removes agent from system | HIGH |
| `create_session` | Creates session tied to root filepath | MEDIUM |
| `get_session_status` | Returns status of all agents in session | LOW |
| `delete_session` | Removes entire session and all agents | HIGH |
| `send_message_to_agent` | Sends message with ADDER+ prepending | MEDIUM |
| `clear_agent_conversation` | Closes current iTerm tab for agent | MEDIUM |
| `start_new_agent_conversation` | Opens new iTerm tab for agent | MEDIUM |
## ADDER+ Workflow Integration
Each agent operates with the comprehensive **ADDER+ (Advanced Development, Documentation & Error Resolution)** protocol, enabling:
- **Autonomous Task Management**: TODO.md-driven execution with real-time progress tracking
- **Advanced Programming Synthesis**: Design by Contract + defensive programming + type-driven development + property-based testing + functional programming patterns
- **Systematic Error Resolution**: Root Cause Analysis with automatic task generation
- **Inter-Agent Coordination**: Task-based communication through documentation files
## Security Model
- **Process Isolation**: Each Claude Code agent runs in separate process
- **Session Boundaries**: Agents cannot access other session codebases
- **State Encryption**: Persistent agent state encrypted at rest
- **Audit Logging**: All agent interactions logged for security analysis
- **Permission Model**: Role-based access control for agent operations
## Quick Start
```bash
# Install dependencies
uv sync
# Start the MCP server
python src/main.py
```
## Claude Desktop Configuration
To use this Agent Orchestration Platform with Claude Desktop, you need to configure it as an MCP server in Claude's configuration file.
### Configuration File Location
**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Windows:**
```
%APPDATA%/Claude/claude_desktop_config.json
```
### Configuration Steps
1. **Open Configuration File**: Navigate to the configuration file location above. Create the file if it doesn't exist.
2. **Add Server Configuration**: Add the following configuration to your `claude_desktop_config.json`:
#### Option 1: Using UV (Recommended)
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP",
"run",
"python",
"src/main.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
#### Option 2: Using Python Directly
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "python",
"args": [
"/ABSOLUTE/PATH/TO/Claude_Code_MCP/src/main.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
#### Option 3: Using Virtual Environment
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/.venv/bin/python",
"args": [
"/ABSOLUTE/PATH/TO/Claude_Code_MCP/src/main.py"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
### Configuration Notes
- **Replace `/ABSOLUTE/PATH/TO/Claude_Code_MCP`** with the actual absolute path to your project directory
- **On Windows**, use backslashes in paths: `C:\\path\ o\\Claude_Code_MCP`
- **Server Name**: You can change `"claude-code-mcp"` to any name you prefer
- **Virtual Environment**: If using a virtual environment, adjust the Python path accordingly
### Advanced Configuration Options
#### With Custom Security Level
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP",
"run",
"python",
"src/main.py",
"--security-level",
"HIGH",
"--max-agents",
"16",
"--max-sessions",
"8"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
#### With Custom Log Directory
```json
{
"mcpServers": {
"claude-code-mcp": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP",
"run",
"python",
"src/main.py",
"--log-dir",
"/ABSOLUTE/PATH/TO/Claude_Code_MCP/logs"
],
"env": {
"PYTHONPATH": "/ABSOLUTE/PATH/TO/Claude_Code_MCP/src"
}
}
}
}
```
### Verification Steps
1. **Save Configuration**: Save the `claude_desktop_config.json` file
2. **Restart Claude Desktop**: Completely quit and restart Claude Desktop
3. **Check MCP Status**: Look for MCP server indicators in the Claude Desktop interface:
- Hammer icon (🔨) indicating available tools
- Connector icon indicating MCP server connection
4. **Test Functionality**: Try using one of the agent orchestration tools
### Troubleshooting
#### Server Not Loading
- Verify all paths are absolute (not relative)
- Check that `uv` or `python` is in your system PATH
- Ensure the project directory exists and has correct permissions
- Review Claude Desktop logs at:
- **macOS**: `~/Library/Logs/Claude/mcp*.log`
- **Windows**: `%APPDATA%\Claude\logs\mcp*.log`
#### Manual Testing
Test the server manually before configuring Claude Desktop:
```bash
# Navigate to project directory
cd /path/to/Claude_Code_MCP
# Test with UV
uv run python src/main.py --help
# Test with Python directly
python src/main.py --help
```
#### Common Issues
- **Permission Errors**: Ensure Claude Desktop has permission to execute the Python interpreter
- **Import Errors**: Verify `PYTHONPATH` is correctly set in the configuration
- **Port Conflicts**: If using HTTP transport, ensure the port (default 8000) is available
### Available MCP Tools
Once configured, Claude Desktop will have access to these agent orchestration tools:
- `create_agent` - Create new Claude Code agent instances
- `delete_agent` - Remove agents from the system
- `create_session` - Create sessions tied to specific codebases
- `get_session_status` - Get status of all agents in a session
- `delete_session` - Remove entire sessions and all agents
- `send_message_to_agent` - Send messages with ADDER+ protocol integration
- `clear_agent_conversation` - Close current iTerm tab for agent
- `start_new_agent_conversation` - Open new iTerm tab for agent
## Development Workflow
1. **Session Creation**: Link sessions to specific codebases
2. **Agent Spawning**: Create specialized agents with custom system prompts
3. **Task Coordination**: Agents communicate through TODO.md and task files
4. **Status Monitoring**: Real-time visibility into agent progress and health
5. **Session Management**: Persistent state with recovery capabilities
## Integration Points
- **FastMCP Framework**: High-performance MCP server implementation
- **iTerm2 Python API**: Advanced terminal session management
- **Claude Code**: AI agent process orchestration
- **Asyncio Architecture**: Event-driven concurrent agent management
This platform enables sophisticated AI development workflows with multiple specialized agents working collaboratively on complex codebases while maintaining strict security isolation and comprehensive audit trails.
