mcp-multiplexer
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-multiplexer
A small, strict MCP multiplexer: one MCP endpoint over many equivalent MCP
servers. The first (reference) server defines the tool contract; members with a
different tool set, schema or version are hidden. Every tool gets a required
selector parameter (base by default) whose enum contains only compatible
members.
This is a reference implementation for the MCPHub feature idea “first-class Multiplexer” — and a working service for 1C data/admin endpoints.
Why
The same MCP server is often deployed many times: one per 1C base, store, tenant
or environment. Prefixing gives you base-a-execute_query,
base-b-execute_query, … and N copies of every schema in the model context.
This service gives you exactly one execute_query with:
"base": { "type": "string", "enum": ["rt", "ut", "cost"] }The model chooses a base; the multiplexer routes the call. Optionally, the
read-only tools can run on all compatible bases in one request ("base": "all").
Related MCP server: mcp-nexus
Strict model
reference(default: the first base) defines the tool names, input schemas and descriptions.Another base is exposed only when all of these match:
exact tool-name set (no extra, no missing tools);
exact normalized
inputSchemafor every tool;exact upstream version from
initialize(version: "ignore"disables this).
An incompatible base is hidden completely: its tools do not appear and its value is not in the enum.
/healthshows the reason.The same tool name may behave differently on different bases (different data, different rows). That is expected: compatibility is about the contract, not the result. The selector chooses the implementation/data set.
If the reference is unavailable at startup, the service fails to start; it never silently switches the reference to another base.
baseis required even when only one member is compatible, so a member recovering does not change the client-visible schema.
Quick start
uv venv --python 3.12
. .venv/bin/activate
uv pip install -e '.[dev]'
cp config/config.example.json config/config.json
# edit config/config.json: URLs, users, passwords, reference, fanOut
MCP_CONFIG=config/config.json python -m mcp_multiplexer
# or:
# MCP_CONFIG=config/config.json uvicorn mcp_multiplexer.app:create_app_from_env \
# --factory --host 0.0.0.0 --port 8010Check:
curl -s http://127.0.0.1:8010/health | jqMCP endpoint: http://127.0.0.1:8010/mcp (Streamable HTTP, stateless, JSON
responses).
Docker
mkdir -p config
cp config/config.example.json config/config.json
# edit config/config.json
docker compose up -d --build
curl -s http://127.0.0.1:8010/healthThe container expects config/config.json mounted read-only at
/config/config.json; it joins the external mcpnet network. No port is
published by default; MCPHub reaches it as http://mcp-multiplexer:8010/mcp.
Config
{
"name": "data-farm",
"groupBy": "base",
"reference": "data_ut",
"compatibility": {
"tools": "exact",
"schemas": "exact",
"version": "exact"
},
"onIncompatible": "hide",
"fanOut": {
"enabled": true,
"tools": ["execute_query", "validate_query"],
"maxConcurrency": 4,
"timeoutMs": 30000
},
"toolsEnabled": [],
"bases": [
{
"name": "data_ut",
"value": "ut",
"url": "http://onec-ws:8080/ut_kz",
"username": "<service user>",
"password": "<password>",
"serviceRoot": "mcp",
"maxConcurrent": 4
},
{
"name": "data_ut_sebestoimost",
"value": "cost",
"url": "http://onec-ws:8080/ut_sebestoimost",
"username": "<service user>",
"password": "<password>",
"serviceRoot": "mcp",
"maxConcurrent": 2
}
]
}Base fields:
Field | Meaning |
| Unique server name (also used for health/logs) |
| Selector value in the enum; defaults to |
| Publication root, without |
| Full JSON-RPC URL, overrides |
| 1C HTTP service root, default |
| Basic auth to the publication |
| Custom headers, e.g. |
| Per-base request limit |
Top-level fields:
Field | Meaning |
| Name of the synthetic selector parameter |
| Canonical base; default first |
|
|
|
|
| Optional parallel read-only calls |
| Optional allowlist of reference tool names |
config/config.admin.example.json shows the APISIX-token variant.
APISIX token auth
If the 1C endpoints are behind APISIX with key-auth, do not point the
multiplexer at onec-ws. Use the public APISIX URL and pass the consumer key in
a header:
{
"name": "admin_forum",
"value": "forum",
"rpcUrl": "https://gateway.example.com/admin/forum/rpc",
"headers": { "X-API-Key": "<apisix consumer admin key>" },
"maxConcurrent": 2
}APISIX checks X-API-Key and injects Authorization: Basic from OpenBao. The
multiplexer does not need the per-base 1C passwords.
Use the public FQDN (https://gateway.example.com), not the internal APISIX port:
APISIX route/consumer ip-restriction sees the NPM source address, which is in
the allowed 10.20.0.0/16; a direct docker-network request would be rejected.
Fan-out
fanOut.tools is an explicit allowlist. For those tools, the selector enum also
contains "all":
{ "name": "execute_query", "arguments": { "query": "SELECT 1", "base": "all" } }The multiplexer calls every compatible member in parallel, applies
maxConcurrency and timeoutMs, and returns a JSON payload with per-target
results:
{
"summary": { "requested": 3, "succeeded": 2, "failed": 1 },
"results": [
{ "target": "rt", "ok": true, "result": { "content": [ ... ] } },
{ "target": "ut", "ok": true, "result": { "content": [ ... ] } },
{ "target": "cost", "ok": false, "error": "timeout after 30000 ms" }
]
}Writes are never fanned out: only explicitly listed tools are eligible, and a single target is still required for everything else.
Deploy on the mcphub host
The service belongs on the same Docker host as MCPHub and onec-ws, in the
mcpnet network. It publishes no host port; MCPHub reaches it by container
name.
Data multiplexer
cd ~/deploy
git clone https://github.com/malikov-pro/mcp-multiplexer.git
cd mcp-multiplexer
cp config/config.example.json config/config.json
$EDITOR config/config.json # URLs, service users, passwords
chmod 600 config/config.json
docker network inspect mcpnet >/dev/null
docker compose up -d --build
docker compose ps
docker logs -f mcp-multiplexerHealth from inside mcpnet (the container does not publish a host port):
docker run --rm --network mcpnet curlimages/curl:8.11.1 \
-s http://mcp-multiplexer:8010/healthAdmin multiplexer
A multiplexer is one homogeneous tool family. Run a second container for
/admin instead of mixing data and admin tools:
cp config/config.admin.example.json config/config.admin.json
$EDITOR config/config.admin.json # APISIX rpcUrl + X-API-Key
chmod 600 config/config.admin.json
docker compose -f compose.admin.yaml up -d --build
docker run --rm --network mcpnet curlimages/curl:8.11.1 \
-s http://mcp-multiplexer-admin:8010/healthIn config.admin.example.json the reference is data_rt_test — the test base's
universal /admin endpoint (https://gateway.example.com/admin/rpc), and
admin_forum is the forum store. Member names are local to the config; both
must expose the same admin tools and version for strict compatibility.
MCPHub
Add one server per multiplexer:
Field | Value |
Name |
|
Type | Streamable HTTP |
URL |
|
Put the server in the matching group and keep the per-base servers out of that group. MCPHub will prefix the tools with the server name, while the multiplexer keeps the selector parameter.
Update / restart
cd ~/deploy/mcp-multiplexer
git pull --ff-only
docker compose up -d --build # data
docker compose -f compose.admin.yaml up -d --build # admin, if usedConfig-only change: docker compose restart mcp-multiplexer (and the admin
equivalent). The config is read at startup.
Common failures
Symptom | Cause |
container restarts, log says | wrong URL/credentials, or reference base is down |
APISIX returns 401 | wrong |
APISIX returns 403 | source IP is outside the route/consumer whitelist; use |
| tool set, schema or version differs from the reference; see |
MCPHub cannot connect | container is not on |
MCPHub
Register this service as one MCP server:
Name:
data-farm(oradmin-farm)URL:
http://mcp-multiplexer:8010/mcpTransport: Streamable HTTP
Put it in a group (for example data) and do not expose the individual
per-base servers in the same group. MCPHub will prefix the tools with the
server name (data-farm-execute_query), while this service keeps the selector
parameter and the strict contract.
The same object model is described in
docs/mcphub-proposal.md: a first-class Multiplexer
object, usable as a group member and shared with users. This repo is the
executable reference for that proposal.
Relation to router-1c-mcp
router-1c-mcp is the closest prior
art: one process for many 1C bases, tools merged by name, a base parameter,
per-base Basic auth and concurrency. This project differs deliberately:
strict reference instead of “oldest extension version wins”;
APISIX token support through
headersandrpcUrl(the Rust router only supports Basic auth and builds/hs/<service_root>/rpcitself);Python and a small codebase focused on
tools/list+tools/call;optional fan-out for read-only tools;
no artifact upload/download, PID lock or retry loop.
Limitations
One multiplexer is one homogeneous tool family: data servers together, admin servers together. Do not mix unrelated tool sets.
The reference must be reachable at startup; incompatible members are hidden and reported in
/health.Catalog refresh is done at startup; restart after changing manifests/tools.
No artifact download/upload, no write fan-out, no nested multiplexers.
No built-in auth for the multiplexer endpoint; put it behind APISIX/MCPHub or keep it on the internal
mcpnet.This is a reference implementation, not a drop-in replacement for the full
router-1c-mcpfeature set.
Tests
. .venv/bin/activate
pytest -q
ruff check src testsThe tests cover strict compatibility, selector injection, hidden members,
fan-out, APISIX headers/rpcUrl, Basic auth, JSON-RPC errors and the MCP
initialize/tools/list/tools/call flow with a mocked upstream.
Prior art
router-1c-mcp — tool matrix and
baseselector for 1C.MCPHub — groups, namespacing and Smart Routing; the multiplexer is intended to sit in front of it.
reaatech/mcp-gateway — fan-out aggregation vocabulary.
See NOTICE for attribution details.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP federation gateway: route, govern and observe agent tools across clouds and MCP servers.
MCP Gateway: wrap any MCP server with cold-start retries, uptime SLA, and per-execution MPP billing.
One MCP endpoint for your company's tools, with per-person sign-in, policy and audit.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAggregate, route, and orchestrate multiple MCP backend servers behind a single MCP endpoint.-
- AlicenseAqualityCmaintenanceEnables AI harnesses to connect to a single MCP endpoint that routes to multiple downstream MCP servers, discovering and executing capabilities on demand while keeping tool schemas out of context.441 npmApache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables clients to connect once and access the union of multiple backend MCP servers' tools through a single unified interface, with namespaced tool routing, capability search, and health isolation.MIT
- AlicenseNot gradedqualityAmaintenanceEnables clients to connect through a unified MCP endpoint that aggregates and routes requests to multiple backend MCP resource servers, exposing their combined tools and resources with optional authentication and management.120 npmMIT