# MCP Bridge

> Per-group MCP JSON-RPC proxy routing AI tool calls to multiple backend MCP servers with tool group filtering

- Skill: `jrennie99-glitch/mcp-bridge` (Agent Skill)
- Install (CLI): `npx skillmds add jrennie99-glitch/mcp-bridge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/mcp-bridge/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/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:

| Group | Default | Source | Prefixes | Description |
|-------|---------|--------|----------|-------------|
| `core` | always on | builtin | -- | Search, research, guidance |
| `intelligence` | on | ruvector | `hooks_` | Self-learning routing, memory, training |
| `agents` | on | ruflo | `agent_`, `swarm_`, `task_`, `session_`, `hive-mind_`, `workflow_`, `coordination_` | Agent lifecycle, swarm coordination |
| `memory` | on | ruflo | `memory_`, `agentdb_`, `embeddings_` | Vector memory, semantic search |
| `devtools` | on | ruflo | `hooks_`, `analyze_`, `performance_`, `github_`, `terminal_`, `config_`, `system_`, `progress_` | Code analysis, profiling, GitHub |
| `security` | off | ruflo | `aidefence_`, `claims_`, `transfer_` | AI defence, PII detection |
| `browser` | off | ruflo | `browser_` | Headless browser automation |
| `neural` | off | ruflo | `neural_`, `daa_` | Neural networks, autonomous agents |
| `agentic-flow` | off | agentic-flow | `agentic_flow_`, `agent_booster_`, `agentdb_` | 66+ specialized agents |
| `claude-code` | off | claude | -- | Anthropic Claude Code |
| `gemini` | off | gemini-mcp | -- | Google Gemini |
| `codex` | off | codex | -- | OpenAI Codex |

**Toggle via environment:**
```bash
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

```bash
# 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

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3001` | HTTP listen port |
| `MCP_BRIDGE_URL` | `http://mcp-bridge:3001` | Bridge URL (for kernel) |
| `RVF_KERNEL_SECRET` | random UUID | HMAC signing secret |
| `MCP_GROUP_*` | varies | Enable/disable tool groups |

## Signal Handling

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