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:

Terminal

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):

bash

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`

text

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

22 backends, 285 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
`clinpgx`	Pharmacogenomics / gene-drug guidelines	ClinPGx	13	clinpgx-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.