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.