mcp-router-local

Zero-dependency local Model Context Protocol (MCP) router. Aggregate multiple MCP servers behind a single endpoint so an LLM client (Claude Desktop, Claude Code, Cursor, or any JSON-RPC 2.0 over stdio/SSE client) connects to one router instead of managing many individual server processes.

Built on native Node.js modules only — child_process, readline, fs, path, http. No runtime dependencies, no third-party parsers, nothing to install but the router itself.

Features

• Single endpoint aggregation — one stdio connection (or one local SSE endpoint) that fronts every configured sub-server.

• Dynamic config discovery — reads mcp-router.config.json from the current working directory: executable paths, arguments, env vars, and per-server behavior.

• Protocol aggregation — spawns every sub-server on startup, performs the MCP handshake, and merges tools/list, resources/list, resources/templates/list, and prompts/list into one unified capability manifest.

• Intelligent routing — tools/call, resources/read, and prompts/get are intercepted, matched to the owning sub-server, forwarded, and the response is safely returned to the client. Tool-name collisions across servers are auto-namespaced.

• Process safety — a crashing sub-server is logged to a local debug file (never stdout, so the JSON-RPC stream stays clean) and restarted with capped exponential backoff. On exit, all children are terminated gracefully (SIGTERM → SIGKILL).

Related MCP server: Agent Aggregator

Requirements

• Node.js ≥ 18 (ESM)

Install

npm install -g mcp-router-local   # global CLI: mcp-router
# or run without installing:
npx mcp-router-local

Quick start

Create mcp-router.config.json in the directory you'll run the router from:

{
  "servers": [
    {
      "id": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    {
      "id": "db",
      "command": "python",
      "args": ["db_mcp_server.py"],
      "env": { "DATABASE_URL": "postgres://localhost/app" }
    }
  ]
}

Then start the router:

mcp-router

Point your LLM client at it. For a client that spawns servers over stdio, configure the command mcp-router (with --config <path> if needed). For example, Claude Code:

{
  "mcpServers": {
    "all-my-servers": {
      "command": "mcp-router",
      "args": ["--config", "/absolute/path/to/mcp-router.config.json"]
    }
  }
}

The router announces itself as a single server exposing the union of every sub-server's tools, resources, and prompts. From the client's perspective there is only one server.

Configuration reference

Server entry (servers[])

Transports

stdio (default)

mcp-router reads line-delimited JSON-RPC from stdin and writes responses to stdout. All diagnostics go to the debug file (and optionally stderr) — stdout carries only JSON-RPC, so your client never sees log noise.

SSE

Set transport.type to "sse", then:

• GET http://host:port/sse — opens the event stream (sends event: endpoint).

• POST http://host:port/message — accepts JSON-RPC bodies, returns 202, and pushes responses over the open stream. Requests received before a client connects are queued and drained on connect.

Handling tool-name collisions

If two sub-servers expose a tool with the same name, the router keeps the first server's name untouched and renames the later one to <serverId>__<toolName>. A warning is written to the debug log:

Tool "shared" exists on both "alpha" and "beta"; exposed as "beta__shared" to avoid collision

Call the renamed tool exactly as exposed; the router strips the prefix and forwards the original name to the owning sub-server.

Crash handling & restart backoff

When a sub-server exits unexpectedly:

1. A clean error is written to the debug file (stderr too if debug.enabled).

2. The router attempts a restart with exponential backoff: 1s, 2s, 4s, 8s, 15s… (capped at 15s), up to maxRestarts.

3. On each restart the router re-runs the handshake, re-gathers capabilities, and rebuilds its routing indexes.

4. A server that stays alive for 2 minutes resets its restart counter.

Demo

A self-contained demo ships in demo/ — no real MCP servers needed:

npm run build
node demo/run.mjs

It starts the router against two built-in mock servers (alpha and beta), runs an initialize handshake, lists the merged tools, and calls tools on both — including the collision-renamed beta__shared — then tears everything down. Open demo/mcp-router.config.json to see the shape it uses.

Development

npm install
npm run type-check   # strict TypeScript
npm run build        # tsup -> dist/index.js + dist/index.d.ts

License

MIT