Skip to main content
Glama

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 server

Add 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/metrics

MCP 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/healthz

Manifests 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.py

2. 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.json

Reports 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 200

Reports 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

MG_BASE_URL

https://www.ebi.ac.uk/metagenomics/api/v2

Upstream MGnify API

MG_API_KEY

(empty)

Optional bearer token

MCP_TRANSPORT

stdio

stdio or http

MCP_HOST

0.0.0.0

HTTP bind host

MCP_PORT

8173

HTTP bind port

MCP_CORS_ORIGINS

*

Comma-separated allowed origins

LOG_LEVEL

info

uvicorn log level

Endpoints

  • POST /mcp — Streamable HTTP MCP transport

  • GET /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, Secret

License

See LICENSE (if present) or the repository hosting service.

Available Tools

23 tools
mgnify_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

    A3.6/5.0

    Scored across 23 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    Related MCP Servers