# 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
```bash
# 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](QUICKSTART.md)
---
## Documentation
**Getting Started:**
- [QUICKSTART.md](QUICKSTART.md) - 5-minute setup guide
- [EXAMPLE_WORKFLOW.md](EXAMPLE_WORKFLOW.md) - Real-world collaboration scenarios
- [PRODUCTION.md](PRODUCTION.md) - Production deployment & test results ⭐ **NEW**
**Production Hardening:**
- [scripts/production/README.md](scripts/production/README.md) - Keep-alive daemons, watchdog, task reassignment ⭐ **NEW**
- [PRODUCTION.md](PRODUCTION.md) - Complete test results with IF.TTT citations
**Security & Compliance:**
- [SECURITY.md](SECURITY.md) - Threat model, responsible disclosure policy
- [YOLO_MODE.md](YOLO_MODE.md) - Command execution safety guide
- Policy compliance: Anthropic AUP, OpenAI Usage Policies
**Contributing:**
- [CONTRIBUTING.md](CONTRIBUTING.md) - Development setup, PR workflow
- [LICENSE](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](PRODUCTION.md)
---
## Development
```bash
# 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](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](PRODUCTION.md) for complete deployment guide
- Use [scripts/production/](scripts/production/) for keep-alive, watchdog, and task reassignment
- Follow [SECURITY.md](SECURITY.md) security best practices
---
## Support
- **Issues:** [GitHub Issues](https://github.com/dannystocker/mcp-multiagent-bridge/issues)
- **Discussions:** [GitHub Discussions](https://github.com/dannystocker/mcp-multiagent-bridge/discussions)
- **Security:** See [SECURITY.md](SECURITY.md) for responsible disclosure
---
## License
MIT License - Copyright © 2025 Danny Stocker
See [LICENSE](LICENSE) for full terms.
---
## Acknowledgments
Built with [Claude Code](https://docs.claude.com/claude-code) and [Model Context Protocol](https://modelcontextprotocol.io/).