Skip to content
Back to search

mcp-multiplexer

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/malikov-pro--mcp-multiplexer/badge.svg)](/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
  1. # mcp-multiplexer
  2. A small, strict **MCP multiplexer**: one MCP endpoint over many equivalent MCP
  3. servers. The first (reference) server defines the tool contract; members with a
  4. different tool set, schema or version are hidden. Every tool gets a required
  5. selector parameter (`base` by default) whose enum contains only compatible
  6. members.
  7. This is a reference implementation for the MCPHub feature idea
  8. [“first-class Multiplexer”](https://github.com/samanhappy/mcphub) — and a
  9. working service for 1C data/admin endpoints.
  10. ## Why
  11. The same MCP server is often deployed many times: one per 1C base, store, tenant
  12. or environment. Prefixing gives you `base-a-execute_query`,
  13. `base-b-execute_query`, … and N copies of every schema in the model context.
  14. This service gives you exactly one `execute_query` with:
  15. ```json
  16. "base": { "type": "string", "enum": ["rt", "ut", "cost"] }
  17. ```
  18. The model chooses a base; the multiplexer routes the call. Optionally, the
  19. read-only tools can run on all compatible bases in one request (`"base": "all"`).
  20. ## Strict model
  21. - `reference` (default: the first base) defines the tool names, input schemas and
  22. descriptions.
  23. - Another base is exposed only when **all** of these match:
  24. - exact tool-name set (no extra, no missing tools);
  25. - exact normalized `inputSchema` for every tool;
  26. - exact upstream version from `initialize` (`version: "ignore"` disables this).
  27. - An incompatible base is hidden completely: its tools do not appear and its
  28. value is not in the enum. `/health` shows the reason.
  29. - The same tool name may behave differently on different bases (different data,
  30. different rows). That is expected: compatibility is about the contract, not
  31. the result. The selector chooses the implementation/data set.
  32. - If the reference is unavailable at startup, the service fails to start; it
  33. never silently switches the reference to another base.
  34. - `base` is required even when only one member is compatible, so a member
  35. recovering does not change the client-visible schema.
  36. ## Quick start
  37. ```bash
  38. uv venv --python 3.12
  39. . .venv/bin/activate
  40. uv pip install -e '.[dev]'
  41. cp config/config.example.json config/config.json
  42. # edit config/config.json: URLs, users, passwords, reference, fanOut
  43. MCP_CONFIG=config/config.json python -m mcp_multiplexer
  44. # or:
  45. # MCP_CONFIG=config/config.json uvicorn mcp_multiplexer.app:create_app_from_env \
  46. # --factory --host 0.0.0.0 --port 8010
  47. ```
  48. Check:
  49. ```bash
  50. curl -s http://127.0.0.1:8010/health | jq
  51. ```
  52. MCP endpoint: `http://127.0.0.1:8010/mcp` (Streamable HTTP, stateless, JSON
  53. responses).
  54. ## Docker
  55. ```bash
  56. mkdir -p config
  57. cp config/config.example.json config/config.json
  58. # edit config/config.json
  59. docker compose up -d --build
  60. curl -s http://127.0.0.1:8010/health
  61. ```
  62. The container expects `config/config.json` mounted read-only at
  63. `/config/config.json`; it joins the external `mcpnet` network. No port is
  64. published by default; MCPHub reaches it as `http://mcp-multiplexer:8010/mcp`.
  65. ## Config
  66. ```json
  67. {
  68. "name": "data-farm",
  69. "groupBy": "base",
  70. "reference": "data_ut",
  71. "compatibility": {
  72. "tools": "exact",
  73. "schemas": "exact",
  74. "version": "exact"
  75. },
  76. "onIncompatible": "hide",
  77. "fanOut": {
  78. "enabled": true,
  79. "tools": ["execute_query", "validate_query"],
  80. "maxConcurrency": 4,
  81. "timeoutMs": 30000
  82. },
  83. "toolsEnabled": [],
  84. "bases": [
  85. {
  86. "name": "data_ut",
  87. "value": "ut",
  88. "url": "http://onec-ws:8080/ut_kz",
  89. "username": "<service user>",
  90. "password": "<password>",
  91. "serviceRoot": "mcp",
  92. "maxConcurrent": 4
  93. },
  94. {
  95. "name": "data_ut_sebestoimost",
  96. "value": "cost",
  97. "url": "http://onec-ws:8080/ut_sebestoimost",
  98. "username": "<service user>",
  99. "password": "<password>",
  100. "serviceRoot": "mcp",
  101. "maxConcurrent": 2
  102. }
  103. ]
  104. }
  105. ```
  106. Base fields:
  107. | Field | Meaning |
  108. |---|---|
  109. | `name` | Unique server name (also used for health/logs) |
  110. | `value` | Selector value in the enum; defaults to `name`; cannot be `all` |
  111. | `url` | Publication root, without `/hs/...` |
  112. | `rpcUrl` | Full JSON-RPC URL, overrides `url`/`serviceRoot` (APISIX use case) |
  113. | `serviceRoot` | 1C HTTP service root, default `mcp`; `admin` for `/admin` |
  114. | `username`/`password` | Basic auth to the publication |
  115. | `headers` | Custom headers, e.g. `X-API-Key` for APISIX |
  116. | `maxConcurrent` | Per-base request limit |
  117. Top-level fields:
  118. | Field | Meaning |
  119. |---|---|
  120. | `groupBy` | Name of the synthetic selector parameter |
  121. | `reference` | Canonical base; default first |
  122. | `compatibility` | `tools`/`schemas`/`version`; `version` may be `ignore` |
  123. | `onIncompatible` | `hide` (default) or `fail` |
  124. | `fanOut` | Optional parallel read-only calls |
  125. | `toolsEnabled` | Optional allowlist of reference tool names |
  126. `config/config.admin.example.json` shows the APISIX-token variant.
  127. ## APISIX token auth
  128. If the 1C endpoints are behind APISIX with `key-auth`, do not point the
  129. multiplexer at `onec-ws`. Use the public APISIX URL and pass the consumer key in
  130. a header:
  131. ```json
  132. {
  133. "name": "admin_forum",
  134. "value": "forum",
  135. "rpcUrl": "https://gateway.example.com/admin/forum/rpc",
  136. "headers": { "X-API-Key": "<apisix consumer admin key>" },
  137. "maxConcurrent": 2
  138. }
  139. ```
  140. APISIX checks `X-API-Key` and injects `Authorization: Basic` from OpenBao. The
  141. multiplexer does not need the per-base 1C passwords.
  142. Use the public FQDN (`https://gateway.example.com`), not the internal APISIX port:
  143. APISIX route/consumer `ip-restriction` sees the NPM source address, which is in
  144. the allowed `10.20.0.0/16`; a direct docker-network request would be rejected.
  145. ## Fan-out
  146. `fanOut.tools` is an explicit allowlist. For those tools, the selector enum also
  147. contains `"all"`:
  148. ```json
  149. { "name": "execute_query", "arguments": { "query": "SELECT 1", "base": "all" } }
  150. ```
  151. The multiplexer calls every compatible member in parallel, applies
  152. `maxConcurrency` and `timeoutMs`, and returns a JSON payload with per-target
  153. results:
  154. ```json
  155. {
  156. "summary": { "requested": 3, "succeeded": 2, "failed": 1 },
  157. "results": [
  158. { "target": "rt", "ok": true, "result": { "content": [ ... ] } },
  159. { "target": "ut", "ok": true, "result": { "content": [ ... ] } },
  160. { "target": "cost", "ok": false, "error": "timeout after 30000 ms" }
  161. ]
  162. }
  163. ```
  164. Writes are never fanned out: only explicitly listed tools are eligible, and a
  165. single target is still required for everything else.
  166. ## Deploy on the mcphub host
  167. The service belongs on the same Docker host as MCPHub and `onec-ws`, in the
  168. `mcpnet` network. It publishes no host port; MCPHub reaches it by container
  169. name.
  170. ### Data multiplexer
  171. ```bash
  172. cd ~/deploy
  173. git clone https://github.com/malikov-pro/mcp-multiplexer.git
  174. cd mcp-multiplexer
  175. cp config/config.example.json config/config.json
  176. $EDITOR config/config.json # URLs, service users, passwords
  177. chmod 600 config/config.json
  178. docker network inspect mcpnet >/dev/null
  179. docker compose up -d --build
  180. docker compose ps
  181. docker logs -f mcp-multiplexer
  182. ```
  183. Health from inside `mcpnet` (the container does not publish a host port):
  184. ```bash
  185. docker run --rm --network mcpnet curlimages/curl:8.11.1 \
  186. -s http://mcp-multiplexer:8010/health
  187. ```
  188. ### Admin multiplexer
  189. A multiplexer is one homogeneous tool family. Run a second container for
  190. `/admin` instead of mixing data and admin tools:
  191. ```bash
  192. cp config/config.admin.example.json config/config.admin.json
  193. $EDITOR config/config.admin.json # APISIX rpcUrl + X-API-Key
  194. chmod 600 config/config.admin.json
  195. docker compose -f compose.admin.yaml up -d --build
  196. docker run --rm --network mcpnet curlimages/curl:8.11.1 \
  197. -s http://mcp-multiplexer-admin:8010/health
  198. ```
  199. In `config.admin.example.json` the reference is `data_rt_test` — the test base's
  200. universal `/admin` endpoint (`https://gateway.example.com/admin/rpc`), and
  201. `admin_forum` is the forum store. Member names are local to the config; both
  202. must expose the same admin tools and version for strict compatibility.
  203. ### MCPHub
  204. Add one server per multiplexer:
  205. | Field | Value |
  206. |---|---|
  207. | Name | `data-farm` / `admin-farm` |
  208. | Type | Streamable HTTP |
  209. | URL | `http://mcp-multiplexer:8010/mcp` / `http://mcp-multiplexer-admin:8010/mcp` |
  210. Put the server in the matching group and keep the per-base servers out of that
  211. group. MCPHub will prefix the tools with the server name, while the multiplexer
  212. keeps the selector parameter.
  213. ### Update / restart
  214. ```bash
  215. cd ~/deploy/mcp-multiplexer
  216. git pull --ff-only
  217. docker compose up -d --build # data
  218. docker compose -f compose.admin.yaml up -d --build # admin, if used
  219. ```
  220. Config-only change: `docker compose restart mcp-multiplexer` (and the admin
  221. equivalent). The config is read at startup.
  222. ### Common failures
  223. | Symptom | Cause |
  224. |---|---|
  225. | container restarts, log says `reference base ... is unavailable` | wrong URL/credentials, or reference base is down |
  226. | APISIX returns 401 | wrong `X-API-Key` in `headers` |
  227. | APISIX returns 403 | source IP is outside the route/consumer whitelist; use `https://gateway.example.com`, not the internal APISIX port |
  228. | `/health` shows a member `incompatible` | tool set, schema or version differs from the reference; see `reason` |
  229. | MCPHub cannot connect | container is not on `mcpnet`, or URL uses a host port instead of the container name |
  230. ## MCPHub
  231. Register this service as one MCP server:
  232. - Name: `data-farm` (or `admin-farm`)
  233. - URL: `http://mcp-multiplexer:8010/mcp`
  234. - Transport: Streamable HTTP
  235. Put it in a group (for example `data`) and do not expose the individual
  236. per-base servers in the same group. MCPHub will prefix the tools with the
  237. server name (`data-farm-execute_query`), while this service keeps the selector
  238. parameter and the strict contract.
  239. The same object model is described in
  240. [`docs/mcphub-proposal.md`](docs/mcphub-proposal.md): a first-class `Multiplexer`
  241. object, usable as a group member and shared with users. This repo is the
  242. executable reference for that proposal.
  243. ## Relation to `router-1c-mcp`
  244. [`router-1c-mcp`](https://github.com/Regsorm/router-1c-mcp) is the closest prior
  245. art: one process for many 1C bases, tools merged by name, a `base` parameter,
  246. per-base Basic auth and concurrency. This project differs deliberately:
  247. - **strict reference** instead of “oldest extension version wins”;
  248. - **APISIX token support** through `headers` and `rpcUrl` (the Rust router only
  249. supports Basic auth and builds `/hs/<service_root>/rpc` itself);
  250. - **Python** and a small codebase focused on `tools/list` + `tools/call`;
  251. - **optional fan-out** for read-only tools;
  252. - no artifact upload/download, PID lock or retry loop.
  253. ## Limitations
  254. - One multiplexer is one homogeneous tool family: data servers together, admin
  255. servers together. Do not mix unrelated tool sets.
  256. - The reference must be reachable at startup; incompatible members are hidden
  257. and reported in `/health`.
  258. - Catalog refresh is done at startup; restart after changing manifests/tools.
  259. - No artifact download/upload, no write fan-out, no nested multiplexers.
  260. - No built-in auth for the multiplexer endpoint; put it behind APISIX/MCPHub or
  261. keep it on the internal `mcpnet`.
  262. - This is a reference implementation, not a drop-in replacement for the full
  263. `router-1c-mcp` feature set.
  264. ## Tests
  265. ```bash
  266. . .venv/bin/activate
  267. pytest -q
  268. ruff check src tests
  269. ```
  270. The tests cover strict compatibility, selector injection, hidden members,
  271. fan-out, APISIX headers/`rpcUrl`, Basic auth, JSON-RPC errors and the MCP
  272. `initialize`/`tools/list`/`tools/call` flow with a mocked upstream.
  273. ## Prior art
  274. - [router-1c-mcp](https://github.com/Regsorm/router-1c-mcp) — tool matrix and
  275. `base` selector for 1C.
  276. - [MCPHub](https://github.com/samanhappy/mcphub) — groups, namespacing and Smart
  277. Routing; the multiplexer is intended to sit in front of it.
  278. - [reaatech/mcp-gateway](https://github.com/reaatech/mcp-gateway) — fan-out
  279. aggregation vocabulary.
  280. See `NOTICE` for attribution details.
  281. ## License
  282. MIT. See `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.