mcp-combiner

mcp-companion

An MCP aggregator (combiner) and editor integration that aggregates multiple Model Context Protocol servers behind a single HTTP endpoint, with first-class CodeCompanion.nvim support.

The combiner runs standalone as a Python process — any MCP-aware client can connect to it over HTTP. The Lua plugin layer adds Neovim-specific features: tool registration, editor context, slash commands, ACP forwarding, and a status UI.

⚠️ The combiner was renamed mcp-bridge → mcp-combiner. The Python package, command, and import are now mcp-combiner / mcp-combiner / mcp_combiner; its admin tools are combiner__*; config env vars are MCP_COMBINER_* (and MCP_COMPANION_COMBINER_URL → MCP_COMPANION_COMBINER_URL). If you ran an earlier build, see combiner/README.md to migrate (reinstall + a one-off OAuth re-auth). The mcp-companion repo and Neovim plugin keep their name.

📖 Rendered documentation: docs.georgeharker.com/mcp-companion

Overview

---

MCP Combiner (standalone)

The combiner is a FastMCP server that proxies all configured MCP servers through a single HTTP endpoint. It works independently of Neovim — any MCP client that speaks HTTP can use it.

Quick start

# Install dependencies
cd combiner
uv sync --frozen

# Run the combiner
uv run python -m mcp_combiner --mcp --config ~/.config/mcp/servers.json --port 9741

# Health check
curl http://127.0.0.1:9741/health

What the combiner does

• Reads a standard mcpServers JSON config (VS Code / Claude Desktop format)
• Spawns and manages stdio servers, connects to HTTP/SSE servers
• Exposes all tools, resources, and prompts through one HTTP endpoint
• Handles environment variable interpolation, OAuth 2.1 auth, schema sanitization
• Provides meta-tools (combiner__status, combiner__enable_server, combiner__disable_server)
• Serves a /health endpoint with server status

Architecture

Internally the combiner is a one-way layered DAG: the serve entry point (--mcp → __main__ · asgi) wires up server, which registers the management & request plane (meta_tools, the /sessions* REST routes, and the tools/list + tool-call middleware) over the domain modules (tool cache/hysteresis, proxy construction, status, schema fixes) and the foundation (persistent connections with self-healing, sharedserver process management, auth, the Neovim back-channel). All mutable state is owned by runtime.CombinerRuntime and mutated only through its methods. The mcp-combiner CLI is a pure client of the management plane; the mockserver module is the instrumentable test upstream. Full internal design notes live in docs/design.md.

Control CLI

mcp-combiner (without --mcp) is a control CLI for a running combiner — the same operations surface the Neovim plugin exposes: