mcpmux

mcpmux

A meta-MCP proxy in Go that lets a coding agent dynamically register, reload, and terminate child MCP servers at runtime through MCP tools themselves. Today, mcpmux multiplexes management tools plus child tools behind one stdio MCP server. It does not yet multiplex the full MCP feature surface.

┌──────────────┐         ┌──────────────────────────────┐
│  MCP Client  │◄─stdio─►│          mcpmux               │
│              │         │  ┌────────────────────────┐   │
│              │         │  │ Management Tools:       │   │
│              │         │  │  • add_server           │   │
│              │         │  │  • remove_server        │   │
│              │         │  │  • reload_server        │   │
│              │         │  │  • list_servers         │   │
│              │         │  └────────────────────────┘   │
│              │         │  ┌────────────────────────┐   │
│              │         │  │ Proxied Tools:          │   │
│              │         │  │  • myserver__tool_a     │   │
│              │         │  │  • myserver__tool_b     │   │
│              │         │  │  • other__tool_x        │   │
│              │         │  └────────────────────────┘   │
│              │         │         │          │          │
│              │         │    ┌────▼───┐ ┌───▼────┐     │
│              │         │    │child 1 │ │child 2 │ ... │
│              │         │    │(stdio) │ │(stdio) │     │
│              │         │    └────────┘ └────────┘     │
└──────────────┘         └──────────────────────────────┘

Install

go install github.com/google/agent-shell-tools/mcpmux@latest

Or build with Bazel:

bazel build //mcpmux
bazel-bin/mcpmux/mcpmux_/mcpmux

The proxy starts with no child servers. Use the management tools to add them:

// tools/call add_server
{"name": "mytools", "command": "node", "args": ["./my-mcp-server.js"]}

// tools/call mytools__some_tool
{"arg1": "value"}

// tools/call reload_server
{"name": "mytools"}

// tools/call remove_server
{"name": "mytools"}

// tools/call list_servers
{}

What's implemented

The current server initializes as MCP 2025-11-25 and advertises:

• tools with listChanged
• logging

Management tools

Tool proxying

• Child tools are namespaced as {server}__{tool} (split on first __)
• The child tool's description and inputSchema are preserved
• Other tool metadata is not currently preserved during re-registration
• Tool calls are forwarded to the correct child's MCP session
• notifications/tools/list_changed is sent to the client on add/remove/reload

Child process lifecycle

• Spawned via os/exec with configurable command, args, env, cwd
• MCP initialize handshake via the SDK's CommandTransport
• Child stderr forwarded to proxy stderr with [name] prefix
• Crash detection via session.Wait() — marks server as crashed, removes its tools
• Graceful shutdown with timeout, falls back to kill if in-flight calls block
• Single-use Child instances with enforced state machine: New -> Starting -> Running -> Stopped|Crashed

Transport

• Proxy serves over stdio (reads stdin, writes stdout)
• Child servers connected over stdio (per-child stdin/stdout pipes)

What's NOT implemented

These MCP spec features are not proxied through mcpmux today:

Additional current limitations:

• Child MCP notifications are not generally bridged to the client
• Child server capabilities are not merged into the mux capability advertisement
• Only child tools are discovered at startup; prompts and resources are not listed or merged

Transport limitations

• No SSE/HTTP child transports (stdio only)
• No config file for pre-registering servers on startup

Testing

# All tests
bazel test //mcpmux/...

# Unit tests only
bazel test //mcpmux/internal/mcpmux:mcpmux_test

# Integration tests (spawns real processes)
bazel test //mcpmux/internal/integration:integration_test

# With race detector
bazel test //mcpmux/... --@rules_go//go/config:race

Security

mcpmux spawns arbitrary child processes via add_server. If the client is not already sandboxed, run mcpmux inside //sandbox to constrain filesystem and process-level effects of child MCP servers.