mcp-combiner
An MCP aggregator — fronts multiple MCP servers behind a single Streamable HTTP endpoint, so
one connection exposes every backend server's tools. Built on
FastMCP. Shareable across clients (via sharedserver), it
powers the mcp-companion Neovim plugin and the
mcp-combiner Claude Code plugin, and works standalone with any MCP client.
PyPI package · command · import package:
mcp-combiner/mcp-combiner/mcp_combiner.
⚠️ Renamed from
mcp-bridge. If you ran an earlier build:
- command/import are now
mcp-combiner/mcp_combiner; reinstall:uv tool uninstall mcp-bridgethenuv tool install …(see Install below).- config env vars
MCP_BRIDGE_*→MCP_COMBINER_*(andMCP_COMPANION_COMBINER_URL→MCP_COMPANION_COMBINER_URL).- OAuth token storage moved to
~/.cache/mcp-combiner/— you'll re-authenticate each MCP server once (old tokens under~/.cache/mcp-companion/are no longer read).
Install
Needs only uv — uvx fetches and runs it, no venv to manage:
uvx mcp-combiner --help # once published to PyPI
# before PyPI (or to track main) — the package lives in the combiner/ subdirectory:
uvx --from "git+https://github.com/georgeharker/mcp-companion#subdirectory=combiner" mcp-combiner
Or install it: uv pip install mcp-combiner (PyPI), or from the repo subdir
uv pip install "git+https://github.com/georgeharker/mcp-companion#subdirectory=combiner".
Usage
mcp-combiner --config /path/to/servers.json --port 9741
Inbound authentication
By default the /mcp endpoint is unauthenticated — fine on loopback, but a
hole the moment you bind beyond 127.0.0.1 (--host) or share the box. Set a
bearer token and every request to /mcp must present Authorization: Bearer <token>:
MCP_COMBINER_AUTH_TOKEN=$(cat ~/secrets/combiner-token) \
mcp-combiner --config … --port 9741
# or, daemon-side:
mcp-combiner --config … --auth-token-file ~/secrets/combiner-token
- Unset (both) → endpoint stays open (default; nothing changes).
--auth-token-filewins over the env var; a blank/unreadable file → stays open.- Scope is the
/mcptool surface only;/healthand the localhost/sessions*control routes are left open. - A missing/wrong token gets a plain
401— noWWW-Authenticate: Bearer, so standards clients surface an honest auth error instead of falling into OAuth / Dynamic Client Registration. Clients present the token pre-emptively.
The companion clients pick the token up from the same MCP_COMBINER_AUTH_TOKEN
env var (Claude Code, OpenCode, Pi, and the Neovim host) — provision it once in
your environment (or via each client's documented hook) and it flows to all of them.
Development
uv sync
pytest
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file mcp_combiner-0.12.0.tar.gz.
File metadata
- Download URL: mcp_combiner-0.12.0.tar.gz
- Upload date:
- Size: 299.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
b3d21eef2a6405e59f1d939f5c8e86767bca66c4dc74334dbe6afb7ade7a4c07
|
|
| MD5 |
9ba2919bfc959912125f7a864b4c2586
|
|
| BLAKE2b-256 |
89435779495520ede415d60361b9c97bb2883e4fff1d1d0ba04c7cb76d636aee
|
Provenance
The following attestation bundles were made for mcp_combiner-0.12.0.tar.gz:
Publisher:
release.yml on georgeharker/mcp-companion
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
mcp_combiner-0.12.0.tar.gz -
Subject digest:
b3d21eef2a6405e59f1d939f5c8e86767bca66c4dc74334dbe6afb7ade7a4c07 - Sigstore transparency entry: 2511202984
- Sigstore integration time:
-
Permalink:
georgeharker/mcp-companion@e7cdd600cef8ac7de324fcf8c5a5a0bbd33c7f6c -
Branch / Tag:
refs/tags/v0.12.0 - Owner: https://github.com/georgeharker
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@e7cdd600cef8ac7de324fcf8c5a5a0bbd33c7f6c -
Trigger Event:
push
-
Statement type:
File details
Details for the file mcp_combiner-0.12.0-py3-none-any.whl.
File metadata
- Download URL: mcp_combiner-0.12.0-py3-none-any.whl
- Upload date:
- Size: 159.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dde26b94831e8c43fd16e8720ae2fcbfd9f7a061358a1993b4fe88562cfff82e
|
|
| MD5 |
df52fed6310333d3cc8c7076157507df
|
|
| BLAKE2b-256 |
d6c42dfc11e1fe8c32856ab78d8b67985222173407164e1ad1eb8d634fcdd575
|
Provenance
The following attestation bundles were made for mcp_combiner-0.12.0-py3-none-any.whl:
Publisher:
release.yml on georgeharker/mcp-companion
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
mcp_combiner-0.12.0-py3-none-any.whl -
Subject digest:
dde26b94831e8c43fd16e8720ae2fcbfd9f7a061358a1993b4fe88562cfff82e - Sigstore transparency entry: 2511203066
- Sigstore integration time:
-
Permalink:
georgeharker/mcp-companion@e7cdd600cef8ac7de324fcf8c5a5a0bbd33c7f6c -
Branch / Tag:
refs/tags/v0.12.0 - Owner: https://github.com/georgeharker
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@e7cdd600cef8ac7de324fcf8c5a5a0bbd33c7f6c -
Trigger Event:
push
-
Statement type:
