dhis2w-mcp-router
A domain-neutral MCP router: front many upstream MCP servers behind two meta-tools so an agent gets lazy, searchable tool discovery instead of a huge up-front tool payload.
It is the portable, MCP-native equivalent of the Claude Agent SDK's ToolSearch — but it works with any MCP client (local models via LM Studio / Ollama / llama.cpp, or cloud agents), not just Claude's SDK.
Why
A big MCP server (e.g. ~337 dhis2-mcp tools) dumps ~49k tokens of tool schemas into context up front —
which overflows small local models and costs cloud models on every call. The single-tool dhis2_cli
bridge avoids that by collapsing everything behind one tool, but then the agent must discover a CLI
(run --help, trial commands) — discovery overhead. The router is the middle ground:
| tool payload | discovery | typed schemas | guardable chokepoint | |
|---|---|---|---|---|
| full MCP server | huge (all schemas) | none | yes | per-tool |
| single-tool bridge | tiny (1 tool) | high (learn a CLI) | no | yes (1 tool) |
| router (this) | tiny (2 meta-tools) | low (search) | yes (search returns schemas) | yes (1 dispatch) |
The two tools
search_tools(query, limit)— matching tools with their namespaced names (server__tool) and input schemas.call_tool(name, arguments)— dispatch one tool to its upstream and return the result.
call_tool is a single chokepoint, so a policy guard sits there — the same security property as the
bridge, with typed discovery on top.
Read-only mode
Set MCP_ROUTER_READONLY=1 (global) or mark a single upstream "readonly": true in the config to run
read-only: write tools are hidden from search_tools and refused by call_tool (a
PermissionError). Tools are classified by their readOnlyHint annotation when present, else by a
read-verb heuristic on the tool name (fail-closed). This is how a local model safely drives the surface
on a shared host — front play read-only and local read-write in the same config.
Config
Point it at any MCP servers via a JSON config (env MCP_ROUTER_CONFIG, default mcp-router.json):
{
"servers": [
{"name": "dhis2", "command": "uv", "args": ["run", "--directory", "/repo", "dhis2w-mcp"],
"env": {"DHIS2_PROFILE": "play42"}}
]
}
Run it as a stdio MCP server: uv run dhis2w-mcp-router.
Ranking
search_tools ranking is pluggable. The default KeywordRanker scores by query-term hits (no deps).
Add an embeddings block (url + model, an OpenAI-compatible /v1/embeddings endpoint — e.g. a
local embedder in LM Studio / Ollama) to rank by semantic similarity instead, which fixes keyword
mis-ranks (e.g. "data element count" → metadata_count first). It is not a silver bullet on terse
queries with a small local embedder; a larger embedder or a hybrid is the further upgrade.
Status
Published to PyPI from 1.2.0, in lockstep with the rest of the dhis2w-* workspace. The core
(core.py) is domain-neutral (FastMCP + httpx only, no dhis2w-* imports), so the same code could
also extract to a standalone mcp-router repo without a rewrite. Whether the router should become the
default MCP surface for all clients (not just small local models) is still gated on the bench-router
numbers — see the roadmap.
1 maintainer
Release files for dhis2w-mcp-router 1.17.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| dhis2w_mcp_router-1.17.0.tar.gz | 9.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| dhis2w_mcp_router-1.17.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 21.5 kB
Release files / dhis2w_mcp_router-1.17.0.tar.gz
| Download URL | dhis2w_mcp_router-1.17.0.tar.gz |
|---|---|
| Size | 9.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
150c7749f78d9de456d7397027d638f7c9439115de275acd7926cf7d5980868d
|
|
BLAKE2b-256 checksum How to use checksums |
bfac4a55a37841542d81e17c0738e2e5ad1979a97da1e52e8cf6969d28c260c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency logRelease files / dhis2w_mcp_router-1.17.0-py3-none-any.whl
| Download URL | dhis2w_mcp_router-1.17.0-py3-none-any.whl |
|---|---|
| Size | 12.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e00bab0bf039c109fe8a3192f77916f5cc5dfd8eee9d35b622b78b8c1f3d80d3
|
|
BLAKE2b-256 checksum How to use checksums |
5106f8c5cca6651bb0665c83930d60654e317a279f9e9f39d2f461b041e8fa28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 11, 2026.
Transparency log
