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

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

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.