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

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

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.

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

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)

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

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:

# 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