Back to search
mcp-multiplexer
MCP serverGitHub
Strict MCP multiplexer: one tool surface over many equivalent MCP servers (reference implementation for MCPHub)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/malikov-pro--mcp-multiplexer)HTML
<a href="/listings/malikov-pro--mcp-multiplexer"><img src="/api/listings/malikov-pro--mcp-multiplexer/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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 8010
Check:
curl -s http://127.0.0.1:8010/health | jq
MCP endpoint: `http://127.0.0.1:8010/mcp` (Streamable HTTP, stateless, JSON responses).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 359 lines
- # 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”](https://github.com/samanhappy/mcphub) — 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:
- ```json
- "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"`).
- ## 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 `inputSchema` for 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. `/health` shows 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.
- - `base` is required even when only one member is compatible, so a member
- recovering does not change the client-visible schema.
- ## Quick start
- ```bash
- 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 8010
- ```
- Check:
- ```bash
- curl -s http://127.0.0.1:8010/health | jq
- ```
- MCP endpoint: `http://127.0.0.1:8010/mcp` (Streamable HTTP, stateless, JSON
- responses).
- ## Docker
- ```bash
- 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/health
- ```
- The 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
- ```json
- {
- "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 |
- |---|---|
- | `name` | Unique server name (also used for health/logs) |
- | `value` | Selector value in the enum; defaults to `name`; cannot be `all` |
- | `url` | Publication root, without `/hs/...` |
- | `rpcUrl` | Full JSON-RPC URL, overrides `url`/`serviceRoot` (APISIX use case) |
- | `serviceRoot` | 1C HTTP service root, default `mcp`; `admin` for `/admin` |
- | `username`/`password` | Basic auth to the publication |
- | `headers` | Custom headers, e.g. `X-API-Key` for APISIX |
- | `maxConcurrent` | Per-base request limit |
- Top-level fields:
- | Field | Meaning |
- |---|---|
- | `groupBy` | Name of the synthetic selector parameter |
- | `reference` | Canonical base; default first |
- | `compatibility` | `tools`/`schemas`/`version`; `version` may be `ignore` |
- | `onIncompatible` | `hide` (default) or `fail` |
- | `fanOut` | Optional parallel read-only calls |
- | `toolsEnabled` | 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:
- ```json
- {
- "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"`:
- ```json
- { "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:
- ```json
- {
- "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
- ```bash
- 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-multiplexer
- ```
- Health from inside `mcpnet` (the container does not publish a host port):
- ```bash
- docker run --rm --network mcpnet curlimages/curl:8.11.1 \
- -s http://mcp-multiplexer:8010/health
- ```
- ### Admin multiplexer
- A multiplexer is one homogeneous tool family. Run a second container for
- `/admin` instead of mixing data and admin tools:
- ```bash
- 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/health
- ```
- In `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 | `data-farm` / `admin-farm` |
- | Type | Streamable HTTP |
- | URL | `http://mcp-multiplexer:8010/mcp` / `http://mcp-multiplexer-admin:8010/mcp` |
- 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
- ```bash
- 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 used
- ```
- Config-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 `reference base ... is unavailable` | wrong URL/credentials, or reference base is down |
- | APISIX returns 401 | wrong `X-API-Key` in `headers` |
- | APISIX returns 403 | source IP is outside the route/consumer whitelist; use `https://gateway.example.com`, not the internal APISIX port |
- | `/health` shows a member `incompatible` | tool set, schema or version differs from the reference; see `reason` |
- | MCPHub cannot connect | container is not on `mcpnet`, or URL uses a host port instead of the container name |
- ## MCPHub
- Register this service as one MCP server:
- - Name: `data-farm` (or `admin-farm`)
- - URL: `http://mcp-multiplexer:8010/mcp`
- - Transport: 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`](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`](https://github.com/Regsorm/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 `headers` and `rpcUrl` (the Rust router only
- supports Basic auth and builds `/hs/<service_root>/rpc` itself);
- - **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-mcp` feature set.
- ## Tests
- ```bash
- . .venv/bin/activate
- pytest -q
- ruff check src tests
- ```
- The 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](https://github.com/Regsorm/router-1c-mcp) — tool matrix and
- `base` selector for 1C.
- - [MCPHub](https://github.com/samanhappy/mcphub) — groups, namespacing and Smart
- Routing; the multiplexer is intended to sit in front of it.
- - [reaatech/mcp-gateway](https://github.com/reaatech/mcp-gateway) — fan-out
- aggregation vocabulary.
- See `NOTICE` for attribution details.
- ## License
- MIT. See `LICENSE`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.