[ARCHITECTURE] MCP-Based Multi-Agent Communication - Replace Tmux

Summary

Research and implement MCP (Model Context Protocol) as the communication layer for multi-agent orchestration, replacing the current tmux-based approach which has proven problematic (terminal rendering issues, dimension mismatches, text parsing fragility).

Problem Statement

Current tmux-based agent communication has significant issues:

• BUG-002: Terminal line sync / width mismatch - garbled output
• Fragile: Relies on tmux capture-pane text scraping
• Not AI-native: Agents communicate via shell text, not structured data
• Scaling issues: Managing 7+ tmux sessions is complex
• No proper error handling: Text-based, no structured responses

Proposed Solution: MCP Protocol

Use Claude Code's native MCP (Model Context Protocol) for agent-to-agent communication.

Architecture

CCPM-Master (MCP Client)
    ↓ HTTP/MCP (ports 8001-8007)
┌───┴───┬───────┬──────────┬─────────┬────────┬────────┐
↓       ↓       ↓          ↓         ↓        ↓        ↓
Backend Frontend Database Integration Testing Docs   Planner
:8001   :8002   :8003      :8004     :8005   :8006   :8007
(Each runs as HTTP MCP Server)

Key Research Findings

1. Claude Code as MCP Server: claude mcp serve exposes tools via stdio
2. HTTP Transport: Need wrapper (Claude Agent SDK) to convert stdio → HTTP
3. Multi-Instance: Fully supported - each agent on different port
4. Authentication: Bearer tokens, API keys, or mTLS supported
5. Tools Exposed: view, edit, ls, bash, grep, custom slash commands

Configuration Example

Master's .mcp.json:

{
  "mcpServers": {
    "backend-agent": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": { "Authorization": "Bearer backend-token" }
    },
    "frontend-agent": {
      "type": "http", 
      "url": "http://localhost:8002/mcp",
      "headers": { "Authorization": "Bearer frontend-token" }
    }
  }
}

Communication Pattern:

# Old (tmux) - fragile text-based
tmux send-keys -t ccpm-backend "Work on Todo #60" Enter

# New (MCP) - structured, AI-native
> @backend-agent please work on Todo #60

Implementation Phases

Phase 1: Proof of Concept

• [ ] Create HTTP MCP proxy wrapper using Claude Agent SDK
• [ ] Deploy one worker (Backend) as HTTP MCP server on localhost:8001
• [ ] Configure Master to connect via MCP
• [ ] Test basic tool execution (view, bash)
• [ ] Verify response handling

Phase 2: Full Deployment

• [ ] Deploy remaining 6 agents as HTTP servers (ports 8002-8007)
• [ ] Create unified .mcp.json configuration
• [ ] Implement token-based authentication
• [ ] Test agent-to-agent communication
• [ ] Benchmark: MCP latency vs tmux latency

Phase 3: Migration

• [ ] Replace tmux send-keys patterns with MCP tool calls
• [ ] Update Master delegation logic
• [ ] Migrate signal-completion to MCP callbacks
• [ ] Update /delegate command to use MCP
• [ ] Deprecate tmux-based communication

Benefits

| Aspect | Tmux (Current) | MCP (Proposed) |
|--------|---------------|----------------|
| Protocol | Shell text | Native AI protocol |
| Communication | Text scraping | Structured JSON |
| Error Handling | Parse output | Proper errors |
| Scaling | Manual sessions | HTTP services |
| Debugging | Read terminal | Tool I/O logs |
| Network | Local only | HTTP anywhere |

Technical Requirements

1. Claude Agent SDK - For HTTP MCP server wrapper
2. Token management - Secure agent authentication
3. Port allocation - 8001-8007 for agents
4. Logging - MCP request/response audit trail

Resources

• MCP Specification
• Claude Code MCP Docs
• Claude Agent SDK

Labels

• type:architecture
• priority:high
• scope:infrastructure

---

🤖 Generated with Claude Code