mcp-multiagent-bridge/README.md

MCP Multiagent Bridge

Production-ready Python MCP server for secure multi-agent coordination with comprehensive safeguards.

Overview

Enables multiple LLM agents (Claude, Codex, GPT, etc.) to collaborate safely through the Model Context Protocol without sharing workspaces or credentials. Built with security-first architecture and production-grade safeguards.

Use cases:

• Backend agent coordinating with frontend agent on different codebases
• Security review agent validating changes from development agent
• Specialized agents collaborating on complex multi-step workflows
• Any scenario requiring isolated agents to communicate securely

---

Key Features

🔒 Security Architecture

Authentication & Authorization:

• HMAC-SHA256 session token authentication
• Automatic secret redaction (API keys, passwords, tokens, private keys)
• 3-hour session expiration with automatic cleanup
• SQLite WAL mode for atomic, race-condition-free operations

4-Stage YOLO Guard™: Command execution (optional) requires multiple confirmation layers:

1. Environment gate - explicit YOLO_MODE=1 opt-in
2. Interactive typed confirmation phrase
3. One-time validation code (prevents automation)
4. Time-limited approval tokens (5-minute TTL, single-use)

Rate Limiting:

• Token bucket algorithm with configurable windows
• Default: 10 requests/minute, 100/hour, 500/day
• Per-session tracking with automatic reset
• Prevents abuse while allowing legitimate bursts

Audit Trail:

• Comprehensive JSONL logging of all operations
• Timestamps, session IDs, actions, results
• Tamper-evident sequential logging
• Supports compliance and forensic analysis

🏗️ Production-Ready Architecture

• Message-only bridge - No auto-execution, returns proposals only
• Schema validation - Strict JSON schemas for all MCP tools
• Command validation - Configurable whitelist/blacklist patterns
• Comprehensive error handling - Graceful degradation, informative errors
• Extensible design - Plugin architecture for future backends

📦 Platform Support

Works with any MCP-compatible LLM:

• Claude Code, Claude Desktop, Claude API
• OpenAI models (via MCP adapters)
• Anthropic API models
• Custom/future models (not tied to specific backend)

---

Installation

# Clone repository
git clone https://github.com/dannystocker/mcp-multiagent-bridge.git
cd mcp-multiagent-bridge

# Install dependencies
pip install mcp>=1.0.0

# Run tests
python test_security.py

Full setup: See QUICKSTART.md

---

Documentation

Getting Started:

• QUICKSTART.md - 5-minute setup guide
• EXAMPLE_WORKFLOW.md - Real-world collaboration scenarios
• PRODUCTION.md - Production deployment & test results ⭐ NEW

Production Hardening:

• scripts/production/README.md - Keep-alive daemons, watchdog, task reassignment ⭐ NEW
• PRODUCTION.md - Complete test results with IF.TTT citations

Security & Compliance:

• SECURITY.md - Threat model, responsible disclosure policy
• YOLO_MODE.md - Command execution safety guide
• Policy compliance: Anthropic AUP, OpenAI Usage Policies

Contributing:

• CONTRIBUTING.md - Development setup, PR workflow
• LICENSE - MIT License

---

Technical Stack

• Python 3.11+ - Modern Python with type hints
• SQLite - Atomic operations with WAL mode
• MCP Protocol - Model Context Protocol integration
• pytest - Comprehensive test suite
• CI/CD - GitHub Actions (tests, security scanning, linting)

---

Project Statistics

• Lines of Code: ~6,700 (including tests, production scripts + documentation)
• Test Coverage: ✅ Core security validated (482 operations, zero failures)
• Documentation: 3,500+ lines across 11 markdown files
• Dependencies: 1 (mcp>=1.0.0, pinned for reproducibility)
• License: MIT

Production Test Results (November 2025)

10-Agent Stress Test:

• ✅ 1.7ms average latency (58x better than 100ms target)
• ✅ 100% message delivery (zero failures)
• ✅ 482 concurrent operations (zero race conditions)
• ✅ Perfect data integrity (SQLite WAL validated)

9-Agent S² Production Hardening:

• ✅ 90-minute test (idle recovery, keep-alive, watchdog)
• ✅ <5 min task reassignment (automated worker failure recovery)
• ✅ 100% keep-alive delivery (30-minute validation)
• ✅ <50ms push notifications (filesystem watcher, 428x faster than polling)

Full Report: See PRODUCTION.md

---

Development

# Install dev dependencies
pip install -r requirements.txt

# Install pre-commit hooks
pip install pre-commit
pre-commit install

# Run test suite
pytest

# Run security tests
python test_security.py

See CONTRIBUTING.md for complete development workflow.

---

Production Status

✅ Production-Ready (Validated November 2025)

Successfully tested with:

• ✅ 10-agent stress test (94 seconds, 100% reliability)
• ✅ 9-agent production deployment (90 minutes, full hardening)
• ✅ 1.7ms average latency (58x better than target)
• ✅ Zero data corruption in 482 concurrent operations
• ✅ Automated recovery from worker failures (<5 min)

Recommended for:

• Production multi-agent coordination
• Development and testing workflows
• Isolated workspaces (recommended)
• Human-supervised operations
• 24/7 autonomous agent systems (with production scripts)

Production deployment:

• See PRODUCTION.md for complete deployment guide
• Use scripts/production/ for keep-alive, watchdog, and task reassignment
• Follow SECURITY.md security best practices

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for responsible disclosure

---

License

MIT License - Copyright © 2025 Danny Stocker

See LICENSE for full terms.

---

Acknowledgments

Built with Claude Code and Model Context Protocol.