MGnify MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MGnify MCP Server find metagenomic studies on human gut microbiome from 2023"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MGnify MCP Server
An MCP (Model Context Protocol) server exposing the MGnify v2 (EBI Metagenomics) API as 23 typed tools an LLM can call directly. Ships with stdio transport for desktop clients and Streamable HTTP transport for Kubernetes deployments, plus health/metrics endpoints and an end-to-end evaluation harness.
What it gives you
23 tools covering biomes, studies, super-studies, samples, runs, analyses, typed annotations (taxonomies + pfams), genome catalogues, genomes, publications.
Two transports:
stdio(Claude Desktop, IDE clients) and HTTP Streamable at/mcp(web/k8s).Production endpoints:
/healthz(liveness),/readyz(verifies upstream MGnify),/metrics(Prometheus text — per-tool call/error counters).Resilient client: retries on 5xx, surfaces 429 with
Retry-After, clamps page sizes; passes through v2's clean{count, items[]}shape unchanged.K8s manifests: Deployment with proper probes, HPA, PDB, ConfigMap, optional Secret, Ingress with streaming-friendly nginx annotations, kustomize entrypoint.
Evaluation harness: 10 verifiable questions, a fast fact-check script, and an LLM-driven runner that measures pass rate, tool calls, latency, tokens.
Perf benchmark for capacity planning (p50/p95/p99 latency, throughput).
Related MCP server: Reactome MCP Server
Quick start (local stdio)
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
python scripts/smoke_test.py # confirm upstream API works
mgnify-mcp # stdio MCP serverAdd it to Claude Desktop's claude_desktop_config.json:
{
"mcpServers": {
"mgnify": {
"command": "/abs/path/to/.venv/bin/mgnify-mcp",
"env": { "MG_BASE_URL": "https://www.ebi.ac.uk/metagenomics/api/v2" }
}
}
}Quick start (HTTP / Docker)
docker compose up --build
curl http://127.0.0.1:8173/healthz
curl http://127.0.0.1:8173/readyz
curl http://127.0.0.1:8173/metricsMCP clients connect to http://127.0.0.1:8173/mcp over Streamable HTTP.
Kubernetes deployment
# 1. Build & push image
make build push REGISTRY=your-registry TAG=v0.2.0
# 2. Point the deployment at it
( cd k8s && kustomize edit set image your-registry/mgnify-mcp=your-registry/mgnify-mcp:v0.2.0 )
# 3. Deploy
kubectl apply -k k8s/
kubectl rollout status deployment/mgnify-mcp
# 4. Verify
kubectl port-forward svc/mgnify-mcp 8173:80 &
curl http://127.0.0.1:8173/healthzManifests included: deployment.yaml (probes + non-root + read-only FS), service.yaml, ingress.yaml (streaming-friendly), configmap.yaml, hpa.yaml (CPU+memory autoscale 2→8), pdb.yaml (minAvailable: 1), secret.yaml (optional MG_API_KEY).
See DEPLOYMENT.md for the long-form runbook.
Measuring effectiveness
Two complementary checks.
1. Fact check (fast, no LLM)
Confirms the 10 expected answers still match upstream MGnify. Run this on a schedule (CI cron) to catch silent staleness.
python evals/check_facts.py2. End-to-end LLM evaluation
Drives a real Claude model against the running MCP server. The model must answer each question by composing tool calls. This is the headline quality metric — if a capable model can't reliably answer, the tools or descriptions are wrong.
export ANTHROPIC_API_KEY=sk-...
pip install -e '.[eval]'
# Server must be running on HTTP transport
python evals/run_eval.py \
--server-url http://127.0.0.1:8173/mcp \
--model claude-opus-4-7 \
--report eval-report.jsonReports pass rate, average latency per question, average tool calls used, and tokens consumed. Treat <90% pass rate as a regression.
3. Latency / throughput benchmark
For capacity planning before bumping replicas or HPA targets:
python scripts/perf_test.py \
--server-url http://127.0.0.1:8173/mcp \
--tool mgnify_list_studies \
--concurrency 20 --requests 200Reports p50/p95/p99 latency, throughput (req/s), error rate. Most latency comes from the upstream MGnify API (~1–2s typical), so set readiness/liveness timeouts accordingly.
Tool catalogue
Biomes (1) · Studies (5) · Super-studies (2) · Samples (3) · Runs (3) · Analyses (3) · Genome catalogues & genomes (4) · Publications (2). All named mgnify_* with Pydantic-validated inputs.
List them at runtime:
python -c "import asyncio; from mgnify_mcp.server import mcp; \
print('\n'.join(t.name for t in asyncio.run(mcp.list_tools())))"Environment variables
Var | Default | Purpose |
|
| Upstream MGnify API |
| (empty) | Optional bearer token |
|
|
|
|
| HTTP bind host |
|
| HTTP bind port |
|
| Comma-separated allowed origins |
|
| uvicorn log level |
Endpoints
POST /mcp— Streamable HTTP MCP transportGET /healthz— Liveness (always 200 if the process is alive)GET /readyz— Readiness (verifies upstream MGnify reachable)GET /metrics— Prometheus text (mgnify_mcp_tool_calls_total,mgnify_mcp_tool_errors_total,mgnify_mcp_uptime_seconds)
Project layout
mgnify_mcp/ # the server package
server.py # FastMCP server + FastAPI wrapper
mgnify_client.py # HTTP client with retries against MGnify v2 OpenAPI surface
schemas.py # Pydantic input schemas
evals/ # evaluation harness
questions.xml # 10 verifiable Q&A pairs
check_facts.py # direct-API fact check (no LLM)
run_eval.py # LLM-driven E2E eval
scripts/
smoke_test.py # quick upstream-API sanity check
perf_test.py # latency / throughput benchmark
build-and-push.sh, deploy.sh
k8s/ # Deployment, Service, Ingress, HPA, PDB, ConfigMap, SecretLicense
See LICENSE (if present) or the repository hosting service.
Available Tools
23 toolsmgnify_analysis_annotationsB
Fetch a typed annotation table for an analysis. annotation_type must be one of: taxonomies__ssu, taxonomies__lsu, taxonomies__its_one_db, taxonomies__unite, taxonomies__pr2, taxonomies__dada2_pr2, taxonomies__dada2_silva, pfams. Pick taxonomies__ssu for 16S/18S ribosomal taxonomy, pfams for protein-family annotation.
Inputs: params (required). Returns: result
mgnify_get_analysisB
Get one analysis by MGnify accession (e.g. 'MGYA00012345'). Includes pipeline_version, downloads, results_dir.
Inputs: params (required). Returns: result
mgnify_get_genomeA
Get one genome by MGnify accession (e.g. 'MGYG000000001'). Returns length, completeness, taxon_lineage, etc.
Inputs: params (required). Returns: result
mgnify_get_genome_catalogueC
Get one genome catalogue by id (e.g. 'human-gut-v2-0-2', 'marine-v2-0').
Inputs: params (required). Returns: result
mgnify_get_publicationA
Get one publication by PubMed id.
Inputs: params (required). Returns: result
mgnify_get_runC
Get one run by accession (e.g. 'ERR1234567').
Inputs: params (required). Returns: result
mgnify_get_sampleB
Get one sample by accession (e.g. 'ERS123456'). Returns title, biome, metadata, related studies.
Inputs: params (required). Returns: result
mgnify_get_studyB
Get a single study by MGnify accession (e.g. 'MGYS00005292'). Returns title, biome, metadata.
Inputs: params (required). Returns: result
mgnify_get_super_studyA
Get a super-study by url-slug (e.g. 'tara-oceans', 'earth-microbiome-project', 'holofood'). Response embeds flagship_studies, related_studies, and genome_catalogues.
Inputs: params (required). Returns: result
mgnify_list_analysesA
List MGnify analyses. The v2 /analyses/ endpoint supports only pagination — use mgnify_study_analyses or mgnify_run_analyses for filtered lookups.
Inputs: params (required). Returns: result
mgnify_list_biomesA
List biomes (environmental categories like soil, marine, gut). Filter by biome_lineage (matches the prefix and all descendants, e.g. 'root:Environmental:Aquatic') and optionally cap depth with max_depth. Each item has biome_name and lineage.
Inputs: params (required). Returns: result
mgnify_list_genome_cataloguesA
List MGnify genome catalogues (e.g. human-gut, marine, chicken-gut). Returns catalogue_id, name, biome label, genome_count, pipeline_version_tag, catalogue_type.
Inputs: params (required). Returns: result
mgnify_list_genomesA
List genomes inside a catalogue. Provide catalogue_id (e.g. 'human-gut-v2-0-2'); v2 only exposes genomes scoped to a catalogue.
Inputs: params (required). Returns: result
mgnify_list_publicationsC
Search publications. Filters: title (substring), published_after/published_before (year), order.
Inputs: params (required). Returns: result
mgnify_list_runsA
List sequencing runs. Filter by has_experiment_type (amplicon|metagenomic|metatranscriptomic|assembly|metabarcoding|hybrid_assembly|long_reads_assembly). For runs filtered by study or sample use mgnify_study_analyses or mgnify_sample_runs instead.
Inputs: params (required). Returns: result
mgnify_list_samplesA
Search samples. Filters: search (accession/title), biome_lineage, order. Use this to discover biological material; then drill into runs/analyses.
Inputs: params (required). Returns: result
mgnify_list_studiesA
Search MGnify studies. Filters: search (titles/accessions), biome_lineage, has_analyses_from_pipeline (e.g. '5.0'), order (accession or updated_at, optionally prefixed '-' for desc). Each item has accession, title, biome, ena_accessions.
Inputs: params (required). Returns: result
mgnify_list_super_studiesC
List super-studies (umbrella collections like Tara Oceans, Earth Microbiome Project, HoloFood).
Inputs: params (required). Returns: result
mgnify_run_analysesB
List analyses produced from a single run.
Inputs: params (required). Returns: result
mgnify_sample_runsB
List sequencing runs taken from a sample.
Inputs: params (required). Returns: result
mgnify_study_analysesC
List analyses produced from a study.
Inputs: params (required). Returns: result
mgnify_study_publicationsA
List publications linked to a study.
Inputs: params (required). Returns: result
mgnify_study_samplesC
List samples that belong to a study.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Every tool targets a distinct entity or relationship: list/get variants for studies, samples, runs, analyses, genomes, catalogues, publications, biomes, and super-studies. Where multiple tools list analyses, their scoping (all, by study, by run) is explicit in descriptions, so an agent should not confuse them.
The set consistently uses the mgnify_ prefix and snake_case, with list_X/get_X for most resources. The relational endpoints (mgnify_study_analyses, mgnify_sample_runs) and the single mgnify_analysis_annotations deviate from the list/get convention, but the pattern is still predictable.
23 tools is above the typical sweet spot, but the domain spans many entity types and each tool maps to a distinct API operation. It is slightly heavy but not bloated.
The read-only domain is covered end-to-end: every core entity has a list and get tool, and relationship tools allow traversal from super-studies/studies to samples to runs to analyses, plus genome catalogues and publications. No obvious dead ends or missing operations for the stated browse/search purpose.
Related MCP Connectors
MGnify — EMBL-EBI's metagenomics resource: public microbiome studies, the biome vocabulary they…
Public MCP endpoint for collaborative research and knowledge discovery.
Model Context Protocol server for Studex tools, notifications, and profile integrations
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that interfaces with Biomart databases, allowing models to discover biological datasets, explore attributes/filters, retrieve biological data, and translate between different biological identifiers.88MIT
- AlicenseAqualityDmaintenanceModel Context Protocol server for accessing Reactome pathway and systems biology data.812MIT
- AlicenseBqualityDmaintenanceA production-ready Model Context Protocol (MCP) server that provides comprehensive access to the BioOntology API for searching, annotating, and exploring over 1,200 biological ontologies.1010MIT
- AlicenseNot gradedqualityDmaintenanceSupports querying and downloading MGnify genome data and performing KEGG functional annotation and module completeness analysis for microbial genomes.1MIT