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

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:

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

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.