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:

bash

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.