vep-link

An MCP (Model Context Protocol) server over the Ensembl REST API, exposing the Variant Effect Predictor and Variant Recoder across both human reference assemblies — GRCh38 (rest.ensembl.org) and GRCh37 (grch37.rest.ensembl.org). It annotates variants, recodes identifiers, resolves any supported input to a canonical genomic coordinate, and lifts coordinates between builds.

Important

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

Why

Ensembl already serves VEP over a public REST API, but it is shaped for scripts, not for models. Its variant endpoints are split by input type, so a caller holding an rsID, an HGVS string and a VCF line must know three different routes; a raw VEP response returns every transcript and every colocated variant, which is far more context than an answer needs; and the two reference assemblies live on two separate hosts with independent uptime.

vep-link collapses that into one surface. Every input — coordinate, CNV, HGVS, rsID, SPDI — is normalized to a canonical CHR-POS-REF-ALT and batched through the single VEP region POST endpoint, then shaped into one of four response_mode tiers so a model pays only for the detail it asked for. Batches are chunked and rate-limited to Ensembl's etiquette, and a per-assembly circuit breaker fails fast with a "retry on the healthy assembly" hint instead of hanging when one build's host is degraded.

Quick start

Hosted — no install required:

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

Local (Python 3.12+, uv). There is no data build step: vep-link is a live-API client and serves as soon as it boots.

uv sync --group dev
make dev                                   # FastAPI /health host + MCP at /mcp on :8000
curl http://127.0.0.1:8000/health
claude mcp add --transport http vep-link http://127.0.0.1:8000/mcp

The Docker stack publishes the container's port 8000 on host port 8021 (docker compose -f docker/docker-compose.yml up); see deployment.

Tools

Tool	Purpose
get_capabilities	Server metadata: assemblies, input formats, VEP-option allowlist, response modes, error codes, citation contract, capabilities_version hash.
resolve_variant	Any input → canonical CHR-POS-REF-ALT (+ gene_symbol, most_severe_consequence).
recode_variant	All equivalent identifiers (rsID, HGVS g./c./p./t., VCF string, SPDI). Single or batch (cap 200).
annotate_variant	Full VEP annotation for one variant, shaped to a response_mode.
annotate_variants_batch	Batch VEP annotation (≤200/call, internal chunking + dedup, per-input errors).
liftover_variant	Lift a coordinate between GRCh37 and GRCh38.
check_upstream_health	Live Ensembl REST readiness per assembly (circuit-breaker snapshot).

Leaf names are intentionally unprefixed per Tool-Naming Standard v1 — namespacing is the gateway's job. Behind genefoundry-router this server mounts under the token vep, so the tools above surface as vep_<tool> (e.g. vep_annotate_variant).

Data & provenance

All annotations come live from the Ensembl REST API — GRCh38 via https://rest.ensembl.org, GRCh37 via https://grch37.rest.ensembl.org. There is no local mirror, no bundle and no ingest: freshness is whatever Ensembl currently serves. Each annotation carries a provenance block stamping the data source, assembly, endpoint and retrieval time. The public endpoint needs no API key, and its precomputed CADD, REVEL, AlphaMissense and GERP predictors are enabled by default (dbNSFP, SpliceAI and LoF are allowlisted but only run on self-hosted VEP instances — see architecture).

The data are Ensembl's, not this repository's: consult Ensembl's legal notice for the terms governing their use.

Required citation, returned verbatim as recommended_citation on every annotation:

McLaren W, et al. The Ensembl Variant Effect Predictor. Genome Biol. 2016;17:122. PMID:27268795.

Documentation

• Usage guide — practical workflows and example tool calls.
• MCP tool reference — per-tool arguments, payloads, and resources.
• Architecture — the normalization pipeline, dual-assembly routing, predictors, circuit breaker, and response_mode tiers.
• Configuration — every VEP_LINK_* variable, the Host/Origin/CORS guards, and the CLI.
• Deployment — Docker, reverse proxy, MCP client configuration, and the stdio entrypoint.
• API reference — REST surface, error envelope, _meta.
• Changelog — release history.
• AGENTS.md — engineering conventions for humans and coding agents.

Contributing

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

License

MIT © Bernt Popp — the code only. The annotations this server returns are Ensembl data, governed by Ensembl's terms and subject to the citation above.