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

# 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

Open Configuration File: Navigate to the configuration file location above. Create the file if it doesn't exist.
Add Server Configuration: Add the following configuration to your claude_desktop_config.json:

Option 1: Using UV (Recommended)

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

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

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

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

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

Save Configuration: Save the claude_desktop_config.json file
Restart Claude Desktop: Completely quit and restart Claude Desktop
Check MCP Status: Look for MCP server indicators in the Claude Desktop interface:
- Hammer icon (🔨) indicating available tools
- Connector icon indicating MCP server connection
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:

# 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

Session Creation: Link sessions to specific codebases
Agent Spawning: Create specialized agents with custom system prompts
Task Coordination: Agents communicate through TODO.md and task files
Status Monitoring: Real-time visibility into agent progress and health
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.