MCP Multiagent Bridge

Lightweight Python MCP server for secure multi-agent coordination with configurable rate limiting, auditable actions, and 4-stage YOLO confirmation flow for safe execution.

MCP Multiagent Bridge coordinates multiple LLM agents via the Model Context Protocol (MCP). Designed for experiments and small-scale deployments, it provides battle-tested security safeguards without sacrificing developer experience. Use it to prototype agent orchestration securely — plug in Claude, Codex, GPT, or other backends without rewriting core code.

⚠️ Beta Software: Suitable for development/testing. See Security Policy before production use.

⚠️ YOLO Mode Warning

This project includes an optional YOLO mode for command execution. This is inherently dangerous and should only be used:

• In isolated development environments

• With explicit user confirmation

• By users who understand the risks

See YOLO_MODE.md and SECURITY.md for details.

Policy Compliance

This project complies with:

• Anthropic Acceptable Use Policy

• Anthropic Responsible Scaling Policy

Users are responsible for ensuring appropriate use and maintaining human oversight of all operations.

Security Features ✅

• HMAC Authentication: Session tokens prevent spoofing

• Automatic Secret Redaction: Filters API keys, passwords, private keys

• Atomic Messaging: SQLite WAL mode prevents race conditions

• Audit Trail: All actions logged with timestamps

• Token Expiration: Conversations expire after 3 hours

• Schema Validation: Strict JSON schemas for all tools

• No Auto-Execution: Bridge returns proposals only - no command execution

• YOLO Guard: Multi-stage confirmation for command execution (when enabled)

• Rate Limiting: 10 req/min, 100 req/hour, 500 req/day per session

Installation

Quick Start

1. Configure MCP Server

Add to ~/.claude.json:

Or use project-scoped config in .mcp.json at your project root.

2. Start Session A (Backend Developer)

3. Start Session B (Frontend Developer)

Tool Reference

create_conversation

Initializes a secure conversation and returns tokens.

Returns:

send_to_partner

Send authenticated, redacted message to partner.

check_messages

Atomically read and mark messages as read.

update_my_status

Heartbeat mechanism to show liveness.

Status values: working, waiting, blocked, complete

check_partner_status

See if partner is alive and what they're doing.

Management CLI

Secret Redaction

The bridge automatically redacts:

• AWS keys (AKIA...)

• Private keys (-----BEGIN...PRIVATE KEY-----)

• Bearer tokens

• API keys

• Passwords

• GitHub tokens (ghp_...)

• OpenAI keys (sk-...)

Redacted content is replaced with placeholders like AWS_KEY_REDACTED.

Security Best Practices

DO ✅

• Keep session tokens secret

• Use separate workspaces for each session

• Poll for messages regularly (every 30s)

• Update status frequently so partner knows you're alive

• Use action_type to clarify message intent

• Review redaction before sending sensitive info

DON'T ❌

• Share tokens in chat messages

• Commit tokens to version control

• Use expired conversations

• Send unrestricted command execution requests

• Assume messages are end-to-end encrypted (local only)

Architecture

Data Flow

1. Session A calls create_conversation → Gets conv_id + token_a + token_b

2. Session A shares conv_id + token_b with Session B

3. Session A calls send_to_partner → Message redacted → Stored in DB

4. Session B calls check_messages → Retrieves + marks read atomically

5. Session B replies via send_to_partner

6. Both sessions update status periodically

Database Schema

• conversations: Conv ID, roles, tokens, expiration

• messages: From/to sessions, redacted content, read status

• session_status: Current status + heartbeat timestamp

• audit_log: All actions for forensics

Limitations & Safeguards

• No command execution: Bridge only passes messages, never executes code

• 3-hour expiration: Conversations auto-expire

• 50KB message limit: Prevents token bloat

• Interactive only: Human must review all proposed actions

• No file sharing: Sessions must use shared workspace or Git

• Local-only: No network transport, Unix socket or stdio only

Testing

Troubleshooting

"Invalid session token"

• Check token hasn't expired (3 hours)

• Verify you're using correct token for your session

• Use bridge_cli.py tokens to retrieve if lost

"No MCP servers connected"

• Verify ~/.claude.json has correct absolute path

• Restart Claude Code after config changes

• Check MCP server logs: claude-code --mcp-debug

Messages not appearing

• Confirm both sessions use same conversation_id

• Check token authentication with bridge_cli.py show

• Verify partner sent messages (check audit log)

Redaction too aggressive

• Review redaction patterns in SecretRedactor.PATTERNS

• Consider adding custom patterns if needed

• False positives are safer than leaking secrets

Use Cases

1. API-First Development

• Session A: Backend - designs API, implements endpoints

• Session B: Frontend - consumes API, provides feedback

• Benefit: Contract-first design with real-time feedback

2. Security Review

• Session A: Feature developer - implements functionality

• Session B: Security auditor - reviews for vulnerabilities

• Benefit: Continuous security assessment

3. Specialized Expertise

• Session A: Python expert - backend services

• Session B: TypeScript expert - React frontend

• Benefit: Each operates in domain of strength

4. Parallel Problem-Solving

• Session A: Investigates bug in module X

• Session B: Implements workaround in module Y

• Benefit: Non-blocking progress on related tasks

Advanced Configuration

Custom Database Location

Adjust Expiration Time

Edit create_conversation method:

Add Custom Redaction Patterns

Edit SecretRedactor.PATTERNS:

Production Hardening (Future)

Current MVP is designed for local development. For production:

• Add TLS for network transport

• Implement rate limiting per session

• Add message size quotas

• Enable sandboxed command execution (Docker)

• Add Redis pub/sub for real-time notifications

• Implement message encryption at rest

• Add role-based access control

• Enable multi-conversation per session

• Add conversation export/import

• Implement backup/restore

License

MIT - Use responsibly. Not liable for data loss or security issues.

Credits

Inspired by Zen MCP Server's multi-model orchestration concepts. Built for secure local multi-agent coordination without external dependencies.