Orchestrates multiple Claude Code agents across iTerm2 terminal sessions using tab-based management, enabling creation and deletion of sessions, agent management, and inter-agent communication through task-based workflows.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Claude Code MCP - Agent Orchestration Platformcreate a new agent for my React project at /Users/alice/projects/ecommerce"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Creates new Claude Code agent instance | HIGH |
| Removes agent from system | HIGH |
| Creates session tied to root filepath | MEDIUM |
| Returns status of all agents in session | LOW |
| Removes entire session and all agents | HIGH |
| Sends message with ADDER+ prepending | MEDIUM |
| Closes current iTerm tab for agent | MEDIUM |
| 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
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:
Windows:
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)
Option 2: Using Python Directly
Option 3: Using Virtual Environment
Configuration Notes
Replace with the actual absolute path to your project directory
On Windows, use backslashes in paths:
C:\\path\ o\\Claude_Code_MCPServer Name: You can change
"claude-code-mcp"to any name you preferVirtual Environment: If using a virtual environment, adjust the Python path accordingly
Advanced Configuration Options
With Custom Security Level
With Custom Log Directory
Verification Steps
Save Configuration: Save the
claude_desktop_config.jsonfileRestart 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
uvorpythonis in your system PATHEnsure the project directory exists and has correct permissions
Review Claude Desktop logs at:
macOS:
~/Library/Logs/Claude/mcp*.logWindows:
%APPDATA%\Claude\logs\mcp*.log
Manual Testing
Test the server manually before configuring Claude Desktop:
Common Issues
Permission Errors: Ensure Claude Desktop has permission to execute the Python interpreter
Import Errors: Verify
PYTHONPATHis correctly set in the configurationPort 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 instancesdelete_agent- Remove agents from the systemcreate_session- Create sessions tied to specific codebasesget_session_status- Get status of all agents in a sessiondelete_session- Remove entire sessions and all agentssend_message_to_agent- Send messages with ADDER+ protocol integrationclear_agent_conversation- Close current iTerm tab for agentstart_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.