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:

Environment gate - explicit YOLO_MODE=1 opt-in
Interactive typed confirmation phrase
One-time validation code (prevents automation)
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

See LICENSE for full terms.

Acknowledgments

Built with Claude Code and Model Context Protocol.