MCP Bridge

MCP Bridge — Multi-Backend Tool Routing Proxy

Express.js service that acts as a central MCP (Model Context Protocol) proxy, spawning and managing multiple backend MCP servers as child processes and routing tool calls from the chat UI to the appropriate backend. Features tool group filtering, guidance engine, and built-in search/research tools.

Purpose

Aggregates tools from multiple MCP backends (ruflo, ruvector, agentic-flow, Claude Code, Gemini, Codex) into a single unified tool list. The chat UI connects to one MCP bridge, which fans out to whichever backends are enabled via environment variables.

Source Location

/tmp/ruflo/ruflo/src/mcp-bridge/

Architecture

Chat UI ──HTTP──> MCP Bridge (Express :3001)
                    |
                    +──stdio──> ruvector  (hooks_ tools)
                    +──stdio──> ruflo     (agent_, swarm_, memory_, etc.)
                    +──stdio──> agentic-flow (agentic_flow_, agent_booster_)
                    +──stdio──> claude    (Claude Code MCP)
                    +──stdio──> gemini-mcp (Gemini context)
                    +──stdio──> codex     (OpenAI Codex)

Tool Groups

Tools are organized into toggleable groups via environment variables. Each group maps tool name prefixes to logical categories:

Toggle via environment:

MCP_GROUP_INTELLIGENCE=false   # Disable intelligence group
MCP_GROUP_SECURITY=true        # Enable security group
MCP_GROUP_BROWSER=true         # Enable browser automation

StdioMcpClient

Each backend runs as a child process communicating over JSON-RPC via stdin/stdout:

• Initialization: Sends initialize with protocol version 2024-11-05, then notifications/initialized, then tools/list
• Tool calls: Routes tools/call requests with original tool names to the correct backend
• Namespacing: Tools are exposed to the AI as {backend}__{original_name} (e.g., ruflo__agent_spawn)
• Timeout: 30-second timeout per request, 60-second startup timeout
• Error handling: Graceful process restart on exit, stderr logging

Built-in Tools (Core Group)

Three built-in tools that are always available:

1. search -- Search knowledge base with natural language queries
2. web_research -- Multi-mode research: search (quick), research (deep report), compare (side-by-side), fact_check (verify claims), goap (comprehensive multi-step with verification)
3. guidance -- AI-facing instruction system explaining available tool groups and usage patterns

Guidance Engine

The guidance tool provides structured instructions to the AI about available capabilities:

• topic: "overview" -- Capabilities summary with decision guide
• topic: "groups" -- Table of all tool groups with status and tool counts
• topic: "{group_name}" -- Detailed usage guide for specific group with key tools and when-to-use advice

MCP STDIO Kernel (mcp-stdio-kernel.js)

Companion STDIO transport for running inside the chat-ui container:

• Acts as a trusted stdio MCP server that forwards to the bridge over HTTP
• HMAC-SHA256 request signing via RVF_KERNEL_SECRET
• Tool registry caching with 60-second TTL
• Handles initialize, tools/list, and tools/call methods

Commands

# Start the bridge
node index.js              # Listens on PORT (default: 3001)
node --watch index.js      # Development mode with auto-reload

# Start the STDIO kernel (inside chat-ui container)
node mcp-stdio-kernel.js   # Reads JSON-RPC from stdin, writes to stdout

Environment Variables

Signal Handling

Clean shutdown on SIGTERM/SIGINT: stops all backend child processes before exiting.