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).

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

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.