Gencc Link

Python 3.12+ CI Conformance License: MIT

An MCP (Model Context Protocol) server that grounds gene-disease validity questions in the Gene Curation Coalition (GenCC) dataset — harmonized across member submitters, with consensus and conflict detection per gene-disease pair.

[!IMPORTANT] Research use only. Not clinical decision support. Do not use for diagnosis, treatment, triage, or patient management.

Why

GenCC has no live API. It ships as a single ~24MB bulk TSV, republished weekly and rate-limited to 20 downloads per IP per day — so an agent cannot query it at all, and a naive integration burns the quota re-downloading it.

Worse, the export is submission-level: one row per submitter assertion. It answers "who said what", never "what does the field think". The judgement a clinician or curator actually wants — is this gene-disease pair settled, and do the curators disagree? — has to be computed.

GenCC-Link builds a local SQLite + FTS5 artifact from that export (fetched conditionally, so an unchanged week costs a 304 and no quota), and precomputes per pair the strongest_classification (highest rank across submitters) and a has_conflict flag when supporting and against assertions coexist. Queries are local, deterministic, and need no upstream at query time.

Quick start

Hosted, no install:

claude mcp add --transport http gencc-link https://gencc-link.genefoundry.org/mcp

Locally (Python 3.12+, uv) — make data is the one required step, the server has no data until the export is downloaded and the database built:

uv sync --group dev
make data                     # download the GenCC export, build data/gencc.sqlite
make dev                      # unified REST + MCP server on http://127.0.0.1:8000
claude mcp add --transport http gencc-link http://127.0.0.1:8000/mcp

make mcp-serve starts the stdio server instead (Claude Desktop; see the MCP connection guide). AUTO_BOOTSTRAP is on by default outside the container, so the HTTP server will build the database on first use if you skip make data — at the cost of a slow, surprising first request. make data-refresh rebuilds only if GenCC published a newer export; make data-info prints build provenance.

Tools

Tool	Purpose
get_server_capabilities	Tool inventory, classification ranks, response modes, data freshness
get_gencc_diagnostics	Build provenance, row/gene/disease/submitter counts, download-quota headroom
search_genes	Resolve symbol / HGNC id / partial text to genes (FTS)
search_diseases	Resolve title / MONDO / OMIM id to diseases (FTS)
resolve_identifier	Map free text to canonical HGNC / MONDO ids
get_gene_curations	Every gene-disease assertion for a gene, with strongest classification + conflict
get_disease_curations	Every gene asserted for a disease, with strongest classification + conflict
get_genes_curations	Batch get_gene_curations: up to 20 genes per call (misses in unresolved)
get_diseases_curations	Batch get_disease_curations: up to 20 diseases per call (misses in unresolved)
get_gene_disease_assertion	One pair: per-submitter classifications, MOI, PMIDs, URLs + conflict analysis
find_curations	Filter assertions by classification / submitter / MOI / conflict (validated enums, ids_only paging, refresh-safe cursor)
list_submitters	Submitting organizations and their submission counts

Leaf names are unprefixed per Tool-Naming Standard v1 — namespacing is the gateway's job. Behind genefoundry-router they surface as gencc_<tool> (e.g. gencc_search_genes). Tools whose payloads vary accept response_mode: minimal | compact (default) | standard | full; see usage for the workflows, the validated filters, and the citation contract.

Data & provenance

• Source: the GenCC bulk submissions export (new format) from thegencc.org — ~24MB TSV, republished weekly, no live API.
• Refresh: conditional (ETag / Last-Modified). An in-app scheduler checks daily and hot-reloads on change; a cron sidecar or Kubernetes CronJob can own it instead. Unchanged exports return 304, which is exempt from GenCC's 20 downloads per IP per day quota — as is HEAD. See data lifecycle.
• Data licence: CC0 1.0 (public domain). Attribution to GenCC and its contributing member organizations (ClinGen, Genomics England PanelApp, Orphanet, Ambry, Invitae, Illumina, and others) is requested.
• OMIM restriction: OMIM disease text is withheld where licensing forbids it, so disease_original_* OMIM fields may be absent. Expected, not a bug.
• Not clinical: GenCC data is not intended for direct diagnostic use or medical decision-making without review by a genetics professional.

Cite GenCC as:

DiStefano MT, et al. The Gene Curation Coalition. Genet Med. 2022;24(8):1732-1742. doi:10.1016/j.gim.2022.04.017

Documentation

• Usage — canonical workflows, response_mode, conflict reading, citation contract, gencc:// resources.
• MCP connection guide — Claude Code and Claude Desktop (HTTP and stdio) configs, verification, troubleshooting.
• Architecture — why SQLite, the consensus/conflict model, transports, error taxonomy, the federation contract.
• Configuration — every GENCC_LINK_* variable (a test owns that claim), the Host/Origin request guard, and CORS.
• Deployment — Docker, Compose overlays, Kubernetes, reverse proxy, quota safety.
• Data lifecycle — build-on-startup, refresh strategies, hot reload.
• Changelog · AGENTS.md — engineering conventions for agentic tools.

Contributing

See AGENTS.md for engineering conventions, the domain notes, and the file-size budget. make ci-local is the definition-of-done gate: format, lint, line budget, README standard, mypy, and tests.

License

MIT © GenCC-Link Contributors. GenCC data is CC0 1.0 (public domain) from thegencc.org; attribution requested.