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

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.