genefoundry-router
A thin FastMCP 3.x aggregator that federates the GeneFoundry *-link MCP fleet behind a
single Streamable-HTTP endpoint. A host adds one server — genefoundry — and gets every
biomedical backend with collision-free <namespace>_<tool> naming and search-based discovery.
[!IMPORTANT] Research use only. Not clinical decision support. Do not use for diagnosis, treatment, triage, or patient management.
Why
An MCP host that mounted all 21 backends directly would face a wall of several hundred tools — more than a model can reason over, and a guarantee of name collisions. The router collapses that into one endpoint and replaces the flat catalog with a search surface, so a model finds the right tool by intent instead of by scrolling.
It is a client to each backend and a server to hosts: it namespaces and shapes the surface, but never rewrites a backend's data. The caller's token is never forwarded upstream.
Quick start
The fleet is hosted — no install required:
claude mcp add --transport http genefoundry https://genefoundry.org/mcp
Health check: genefoundry.org/health.
To run your own against the live fleet (Python 3.12+, uv):
uv sync --group dev
cp .env.example .env # set GF_*_URL backend URLs and GF_AUTH_MODE
uv run genefoundry-router run --host 127.0.0.1 --port 8000
curl -s localhost:8000/health | python -m json.tool
An offline fake fleet (make dev-fleet + make run-dev, or one-shot make test-e2e) runs
the real router against impersonated backends over real Streamable-HTTP — no Docker, no
network.
Tools
The router does not surface the federated catalog flat. A model sees three things:
| Tool | Purpose |
|---|---|
search_tools | Relevance search over the entire federated catalog |
call_tool | Invoke a hit by its <namespace>_<tool> name |
| pinned entry points | Each backend's front-door tool, always visible — declared per-backend as entrypoints: in servers.yaml |
search_tools(query="splicing prediction") # → spliceai_predict_splicing (+ schema)
call_tool(name="spliceai_predict_splicing", arguments={...})
Pinning makes each domain's canonical tool reachable deterministically rather than by relevance luck. See How discovery works — including the two traps that bite MCP clients.
Federated backends
21 backends, 272 tools, each surfaced namespaced — e.g. gnomad_search_genes.
| Namespace | Domain | Data source | Tools | Repo |
|---|---|---|---|---|
pubtator | Literature & entity annotation | PubTator3 | 35 | pubtator-link |
gnomad | Variant / gene / population frequency | gnomAD | 22 | gnomad-link |
orphanet | Rare disease ontology & associations | Orphadata | 19 | orphanet-link |
clingen | Gene–disease curation | ClinGen | 17 | clingen-link |
hpo | Phenotype ontology & associations | Human Phenotype Ontology | 17 | hpo-link |
mavedb | Variant-effect assay scores | MaveDB | 15 | mavedb-link |
uniprot | Protein function | UniProt | 15 | uniprot-link |
genereviews | Gene–disease literature | GeneReviews | 13 | genereviews-link |
mgi | Mouse phenotype & models | MGI | 13 | mgi-link |
mondo | Disease ontology / cross-references | Mondo | 13 | mondo-link |
gencc | Gene–disease curation | GenCC | 12 | gencc-link |
metadome | Protein tolerance landscapes | MetaDome | 11 | metadome-link |
stringdb | Protein–protein interaction networks | STRING | 10 | stringdb-link |
gtex | Tissue expression | GTEx Portal | 9 | gtex-link |
hgnc | Gene nomenclature | HGNC | 9 | hgnc-link |
panelapp | Diagnostic gene panels & curation | PanelApp | 9 | panelapp-link |
autopvs1 | Variant ACMG PVS1 | AutoPVS1 | 7 | autopvs1-link |
spliceai | Splicing prediction | SpliceAI Lookup | 7 | spliceailookup-link |
vep | Variant annotation / consequence | Ensembl VEP | 7 | vep-link |
clinvar | Variant clinical significance | ClinVar | 6 | clinvar-link |
litvar | Variant literature | LitVar2 | 6 | litvar-link |
Data & provenance
The router serves no data of its own; each backend owns its sources, licences and citation guidance, and the router mirrors their disclaimers.
What it does own is integrity of the tool surface. A backend can serve a clean tool at
review time and later change its definition — the channel for a rug pull. The router
fingerprints every normalized tool definition and diffs the live fleet against a reviewed,
packaged baseline (genefoundry_router/data/fleet-baseline.json), enforced at startup and
on a schedule. See Deployment → drift detection.
Documentation
- Configuration & authentication — every
GF_*variable, the OAuth/JWT resource-server modes, and the startup guards. - Deployment — container release, digest pinning, rollback, and drift detection.
- How discovery works — the search surface, entry-point pinning, and how discoverability is measured.
- Design spec — the architecture and why it is shaped this way.
- Fleet standards — Tool-Naming · Response-Envelope · MCP-Behaviour · Tool-Surface-Budget · Tool-Schema-Documentation · Container-Hardening · Versioning · README.
Contributing
See AGENTS.md for engineering conventions. make ci-local is the
definition-of-done gate: format, lint, line budget, README standard, mypy, and tests.
License
MIT © Bernt Popp. Each federated backend carries the licence and citation terms of its upstream data source; see that backend's repository.