Evo2-7B Bioinformatics MCP Server

An MCP (Model Context Protocol) Tools server that wraps the NVIDIA-hosted Evo2-7B Forward API, letting agents like Claude Code, Cursor, and Codex drive Evo2 with natural language:

Agent
  ↓
MCP Tool
  ↓
Evo2 MCP Server（本项目）
  ↓
NVIDIA Evo2-7B Forward API
  ↓
forward outputs → likelihood / variant scores
  ↓
Agent

POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward
Authorization: Bearer $NVIDIA_API_KEY

1. Project Introduction

Provides 5 MCP Tools:

This project is a Bioinformatics MCP Tool Server, not a simple HTTP API wrapper:

• Auto-validates / normalizes DNA sequences (uppercase, whitespace removal, explicit errors for illegal characters)

• Computes likelihood based on official semantics (byte-level tokenizer + causal shift, see §17)

• Layered output design (summary / raw / save) to prevent MCP context explosion

• Complete error classification (400/401/403/404/408/413/422/429/5xx/timeout) + retry/backoff

• API Key is only read from environment variables, never hardcoded, never logged

• Bundled batch scripts: scripts/score_fasta.py (batch FASTA scoring + embedding extraction, see §18) and scripts/analyze_run.py (clustering/classification/regression downstream analysis, see §19)

Related MCP server: Evo2 MCP Server

2. Evo2 API Introduction

Evo2 (Arc Institute / NVIDIA) is a DNA foundation model (StripedHyena2 architecture), with the 7B version having 32 layers, Apache-2.0 licensed, and a training context of up to 1M bp. NVIDIA provides a hosted NIM service:

• Forward endpoint: POST https://health.api.nvidia.com/v1/biology/arc/evo2-7b/forward

• Request body (official OpenAPI ForwardInputs):

  { "sequence": "ACGTACGT...", "output_layers": ["output_layer"] }

  output_layers supports 1–100 layer names (e.g. output_layer, decoder.layers.24.mlp.linear_fc2, decoder.layers.3.self_attention, embedding, decoder.final_norm).

• Response body (official OpenAPI ForwardOutputs): {"data": "<base64-encoded NPZ>", "elapsed_ms": <int>}; oversized responses may be returned with Content-Type: application/zip (raw NPZ bytes).

• output_layer = final logits, shape [seq_len, batch_size, 512] (512 is the padded vocabulary size of the byte-level tokenizer).

⚠️ Deprecation notice (verified 2026-08-24): the arc/evo2-7b endpoint hosted on build.nvidia.com is marked Deprecated (the page shows "This NIM Endpoint has been deprecated"). The official NIM documentation (docs.nvidia.com/nim/bionemo/evo2/latest/) describes an API identical to the hosted endpoint; if the hosted endpoint is unavailable, you can switch to a self-hosted NIM container and point EVO2_MCP_BASE_URL to http://localhost:8000/biology/arc/evo2.

Verified Official Facts (implementation basis, 2026-08-24)

Differences Between Live Testing and Documentation (2026-08-24 live verification, task requires recording the actual interface)

Probing the hosted health.api.nvidia.com endpoint with a real key revealed that the layer names in the documentation do not apply to the hosted endpoint:

Mitigation (implemented and live-verified):

• Added EVO2_MCP_LOGITS_LAYER config (default auto): scoring tools first try the documented name output_layer; if a 422 has no attribute error is received (hosted endpoint), they automatically switch to unembed and cache the result, avoiding repeated probing afterward; self-hosted NIM 2.x containers succeed on the first try with zero extra requests.

• The NPZ parser supports both bare keys (output_layer) and <name>.output (unembed.output) key formats, with a "last dimension = 512" heuristic fallback.

• 422 error messages now hint at the attribute names available on the hosted endpoint.

If the returned seq_len does not match the input sequence length (e.g. the server added padding/BOS), this server refuses to compute likelihood and returns raw statistics with a clear explanation, never guessing the alignment.

3. How to Get an NVIDIA API Key

1. Open https://build.nvidia.com/, click Get API Key in the top-right corner (requires an NVIDIA account login).

2. Create a key (in the form nvapi-xxxxxxxx...).

3. Set it in an environment variable, do not write it into code / config / Git:

   export NVIDIA_API_KEY="nvapi-xxxxxxxx"

   Or copy .env.example to .env and fill it in (.env is ignored by .gitignore).

4. Installation

# 推荐：pip / uv
pip install -e ".[dev]"
# 或
uv sync --extra dev

# 推荐（本项目自带）：pixi 项目本地环境
pixi install
pixi run test

Requires Python >= 3.10 (3.11+ recommended). Core dependencies: mcp>=2.0, httpx>=0.27, numpy>=1.26, pydantic>=2.6, python-dotenv>=1.0. The analysis script (scripts/analyze_run.py) additionally requires dev dependencies: scikit-learn, pandas, matplotlib.

5. Environment Variables

6. CLI Startup

# 三种方式等价
python -m evo2_mcp
evo2-mcp
uv run evo2-mcp      # 用 uv 管理的项目环境
# pixi 环境：
pixi run evo2-mcp

The server communicates with MCP clients via stdio; there will be no output after a normal startup (waiting for the MCP handshake).

7. MCP Configuration

Claude Code (.mcp.json)

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "NVIDIA_API_KEY": "${NVIDIA_API_KEY}"
      }
    }
  }
}

Note: whether ${NVIDIA_API_KEY} is expanded by the client depends on the client implementation. The most reliable approach is to fill in the real key directly:

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "NVIDIA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

But never commit a .mcp.json containing a real key to Git (add the file to .gitignore, or inject it via environment variables / a secret management tool). You can also omit env and let the server process read NVIDIA_API_KEY from its own environment or .env:

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"]
    }
  }
}

Cursor (~/.cursor/mcp.json or project .cursor/mcp.json)

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": { "NVIDIA_API_KEY": "YOUR_API_KEY" }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.evo2]
command = "uv"
args = ["run", "evo2-mcp"]
env = { "NVIDIA_API_KEY" = "YOUR_API_KEY" }

Self-hosted NIM

{
  "mcpServers": {
    "evo2": {
      "command": "uv",
      "args": ["run", "evo2-mcp"],
      "env": {
        "EVO2_MCP_BASE_URL": "http://localhost:8000/biology/arc/evo2"
      }
    }
  }
}

8. Tool List

evo2_forward(sequence, output_layers=["output_layer"], mode="summary", save_path=None)

Runs Evo2-7B forward inference on a DNA sequence. mode:

• "summary" (default): returns shape / dtype / min / max / mean / std per layer, context-safe;

• "save": saves the raw tensor as .npz (output/evo2_forward_<timestamp>.npz), returns the path;

• "raw": inlines the full tensor (only when the total element count ≤ EVO2_MCP_RAW_INLINE_MAX, default 4096, to prevent context explosion).

Layer name note: the hosted health.api.nvidia.com endpoint accepts model attribute names (use unembed for logits; also available are embedding_layer, norm, blocks.N.mlp); the documented names output_layer/decoder.layers.N.* only apply to self-hosted NIM 2.x containers. evo2_score/evo2_variant_score/evo2_batch_score/evo2_score_fasta auto-detect, so no manual specification is needed; only when calling evo2_forward directly do you need to choose the name based on the actual endpoint.

evo2_score(sequence, include_per_position=False)

Computes Evo2's likelihood for a sequence:

{
  "sequence_length": 123,
  "total_log_likelihood": -123.45,
  "mean_log_likelihood": -1.2345,
  "scored_positions": 122,
  "per_position_log_likelihood": null,
  "method_notes": "...",
  "disclaimer": "..."
}

Semantics (consistent with the official Arc implementation): logits[i] predicts the base at position i+1; after log-softmax over the full 512 vocab, take the target base's byte index; position 0 does not participate in scoring, so scored_positions = length - 1, and mean is the average of these N-1 values. per_position_log_likelihood[k] corresponds to 0-based position k+1 of the sequence (i.e. 1-based position k+2). If the seq_len returned by the API cannot be aligned with the sequence, no fabricated results are produced; raw statistics are returned with a clear explanation:

Likelihood calculation is not supported until the API output format is verified.

evo2_variant_score(sequence, position, ref, alt, coordinate="1-based", include_per_position=False)

{
  "position": 100,
  "ref": "A",
  "alt": "G",
  "wildtype_log_likelihood": -500.1,
  "mutant_log_likelihood": -500.5,
  "delta_log_likelihood": -0.4,
  "interpretation": "The mutant sequence is less likely than the wildtype under Evo2-7B ... (NOT a clinical pathogenicity call)"
}

Validation chain: position range → coordinate conversion → ref must match the base at that position in the sequence → ref≠alt → 1-based position 1 (0-based 0) cannot be scored (a causal LM cannot assign a probability to the first token) → explicit error.

evo2_batch_score(sequence, variants, coordinate="1-based")

{
  "sequence_length": 300,
  "wildtype_log_likelihood": -1200.0,
  "variants": [
    { "position": 100, "ref": "A", "alt": "G", "delta_log_likelihood": -0.42 },
    { "position": 200, "ref": "C", "alt": "T", "delta_log_likelihood": 0.13 }
  ]
}

• WT forward is computed only once and reused for all variants;

• Identical (position, alt) mutants are only forwarded once (memoized);

• Concurrency is limited by EVO2_MCP_MAX_CONCURRENCY (default 2, respecting NVIDIA rate limits);

• A single variant failure does not affect the whole batch (each entry returns its own error).

evo2_score_fasta(fasta_path=None, fasta_text=None)

>sequence_1
ACGTACGT...
>sequence_2
TTGGCCAA...

• fasta_text: inline FASTA (available by default, with size/record-count limits);

• fasta_path: only readable if the file is inside EVO2_MCP_ALLOWED_DIRS, otherwise explicitly rejected;

• Returns total_log_likelihood / mean_log_likelihood per record; a single record's error does not affect the rest.

9. Usage Examples

{
  "sequence": "acgtACGT acgt",           // 小写 + 空白自动处理
  "output_layers": ["output_layer"],
  "mode": "summary"
}

Returns:

{
  "sequence_length": 12,
  "requested_output_layers": ["output_layer"],
  "returned_layers": ["output_layer"],
  "layer_stats": [
    { "name": "output_layer", "shape": [12, 1, 512], "dtype": "float32",
      "size": 6144, "min": -3.21, "max": 4.02, "mean": 0.01, "std": 0.98 }
  ],
  "api": { "elapsed_ms": 87 }
}

When an agent wants the full logits:

{ "sequence": "ACGT...", "mode": "save" }

{
  "saved": true,
  "path": "/abs/path/output/evo2_forward_20260824_153000.npz",
  "bytes_on_disk": 24576,
  "layer_stats": [...]
}

10. FASTA Example

{
  "fasta_text": ">geneA\nACGTACGTACGT\n>geneB\nTTGGCCAATTGG"
}

(or "fasta_path": "/data/genomes/genes.fa", requires configuring EVO2_MCP_ALLOWED_DIRS=/data/genomes)

For large-scale FASTA scoring (e.g. an entire directory of enhancers/promoters) plus embedding extraction, use scripts/score_fasta.py (see §18) — each run outputs an independent run folder (scores.csv + embeddings.npz).

11. Variant Scoring Example

{
  "sequence": "ACGTACGTACGTACGTACGT",
  "position": 10,
  "ref": "A",
  "alt": "G"
}

12. Batch Scoring Example

{
  "sequence": "ACGTACGTACGTACGTACGT",
  "variants": [
    { "position": 10, "ref": "A", "alt": "G" },
    { "position": 12, "ref": "T", "alt": "C" },
    { "position": 14, "ref": "A", "alt": "T" }
  ]
}

Typical agent workflow (corresponding to "analyze all SNPs on the sequence, find the top 20 with the largest Evo2 score changes"):

读取输入 → 解析 DNA / VCF → 生成 WT / mutant → evo2_batch_score
→ 按 |delta_log_likelihood| 排序 → 取前 20 → 保存 CSV → 解释结果

13. Error Handling

All errors are returned through MCP as structured JSON: {"error": "Evo2APIError", "message": "..."}. In evo2_batch_score, a single failed item returns {"error": ..., "status": ...} without interrupting the whole batch.

14. Rate limit

NVIDIA's hosted NIM has rate limits. Design countermeasures:

• EVO2_MCP_MAX_CONCURRENCY (default 2) limits concurrency;

• 429 → exponential backoff (1s, 2s, 4s, 8s, 16s…, capped at 30s + jitter; if Retry-After is present, follow it first but cap at 60s);

• Retry cap EVO2_MCP_MAX_RETRIES (default 4), never retries indefinitely;

• Within a batch, WT is scored only once and identical mutants are deduplicated, reducing the number of requests.

15. Security notes

• API Key: read only from the NVIDIA_API_KEY environment variable (or .env); no hardcoded keys anywhere in the code; logs record only URLs, sequence lengths, and layer names, never sequence content or keys; error messages contain only a 500-character summary of the response.

• Sequence privacy: all logs/errors contain only a preview (e.g. ACGT...GCTA (len=12345)).

• Path sandbox:

  • FASTA reading is limited to EVO2_MCP_ALLOWED_DIRS; when not configured, all local paths are rejected;

  • save_path in mode="save" must be inside EVO2_MCP_OUTPUT_DIR;

• .gitignore already includes .env, *.env, output/, *.npz.

• N bases: rejected by default with a clear error (the Evo2 model has not been evaluated on ambiguous bases; the docs only guarantee that A/C/G/T are meaningful). If you really need to pass N through, start with EVO2_MCP_ALLOW_AMBIGUOUS=1 — this is an explicit choice, not silent dropping.

• Don't execute: this server performs no shell execution; Agents can only trigger restricted HTTP requests through FASTA/sequence input.

16. Biological interpretation limits

• Evo2 score is a model-based sequence likelihood change, not experimental evidence, and certainly not a clinical pathogenicity diagnosis.

• delta_log_likelihood < 0 can only be interpreted as "the mutant sequence is less likely under the model", not as "pathogenic".

• Downstream validation (experiments, population frequency, ClinVar annotations, protein structure impact, etc.) is required before discussing pathogenicity.

• Every Tool's description carries the following disclaimer (visible to MCP clients):

This is a DNA foundation model inference tool. It does not provide clinical
diagnosis. Model scores should not be interpreted as pathogenicity labels
without additional validation.

17. Implementation basis and validation sources (2026-08-24)

• NVIDIA NIM for Evo 2 — Endpoints: https://docs.nvidia.com/nim/bionemo/evo2/latest/endpoints.html

• NVIDIA NIM for Evo 2 — Quickstart: https://docs.nvidia.com/nim/bionemo/evo2/latest/quickstart-guide.html

• NVIDIA hosted API reference (arc/evo2-7b-forward OpenAPI schema): https://docs.api.nvidia.com/nim/reference/arc-evo2-7b-infer

• Hosted endpoint tested live (2026-08-24, real key): output_layer returns 422 StripedHyena has no attribute 'output_layer'; unembed returns logits (NPZ key unembed.output, shape (1, seq, 512), float64) — therefore the scoring tool defaults to EVO2_MCP_LOGITS_LAYER=auto for automatic detection

• Batch tested live (2026-08-25, real key, 3800+ K562 enhancer/promoter sequences):

  • Sequences > ~100 kb return 422 from the hosted endpoint (PyTorch canUse32BitIndexMath limit) — use --skip-longer-than 100000 for batch runs;

  • The race condition in automatic layer-name detection under concurrency has been fixed (forward_logits uses a local variable to record attempted names) and a regression test was added;

  • Embedding extraction: norm/embedding_layer/blocks.N all work, shape (1, seq, 4096) float64 (4096 dimensions after mean-pooling).

• Arc Institute Evo2 repository (scoring.py, models.py): https://github.com/ArcInstitute/evo2

• vortex CharLevelTokenizer (Evo2's official tokenizer implementation): PyPI vtx 1.1.0 source vortex/model/tokenizer.py

• Evo2 model card: https://huggingface.co/ArcInstitute/evo2_7b

If NVIDIA adjusts the API, defer to the latest official docs; EVO2_MCP_BASE_URL can be switched at any time.

18. Batch scoring and embedding extraction (scripts/score_fasta.py)

MCP Tools are suited for interactive Agent calls; large-batch FASTA scoring uses the companion script scripts/score_fasta.py (validated against the real API with 3800+ K562 enhancer/promoter sequences).

Each run automatically creates a separate timestamped folder:

output/run_20260825_104403/
├── scores.csv            # 每序列一行：id, header, length, total/mean LL, ...
│                         #   + embedding_key（与 embeddings.npz 的 record_ids 对齐）
└── embeddings.npz        # embeddings: (n, 4096) float32 mean-pooled 矩阵
                          # record_ids: 与矩阵行一一对应的键（来源__序列id）

# 小样本（指定 id）
.pixi/envs/dev/bin/python scripts/score_fasta.py \
  --fasta /path/cis/enhancers.fa /path/cis/promoters.fa \
  --ids K562_TE_629,K562_MPT_6842 --allow-ambiguous

# 全量（跳过 >100kb —— 托管端对该长度返回 422；保留原始 embedding）
.pixi/envs/dev/bin/python scripts/score_fasta.py \
  --fasta /path/cis/enhancers.fa /path/cis/promoters.fa \
         /path/trans/enhancers.fa /path/trans/promoters.fa \
  --skip-longer-than 100000 --allow-ambiguous \
  --embedding-layer norm --keep-raw-embeddings

Key parameters:

Efficiency design: each sequence sends only one request (output_layers=["unembed","norm"], logits and embedding fetched together); the logits layer name is probed only once per run; concurrency is limited by a semaphore.

19. Embedding association and downstream analysis (scripts/analyze_run.py)

embeddings.npz contains mean-pooled sequence representations (one 4096-dimensional vector per sequence), suitable for direct clustering, classification, and regression. Loading and association:

import csv, numpy as np

run = "output/run_20260825_104403"
rows = list(csv.DictReader(open(f"{run}/scores.csv")))
d = np.load(f"{run}/embeddings.npz", allow_pickle=True)
X = d["embeddings"]                        # (n, 4096) float32
ids = [str(x) for x in d["record_ids"]]    # 与 X 行一一对应
key_to_row = {r["embedding_key"]: r for r in rows if r.get("embedding_key")}
scores = [key_to_row[k] for k in ids]      # scores[i] ↔ X[i]

Run the full analysis in one command (KMeans clustering, enhancer-vs-promoter classification, embedding→likelihood regression, PCA plot):

.pixi/envs/dev/bin/python scripts/analyze_run.py output/run_20260825_104403 --k 3

Outputs analysis_<run>.npz (merged X + keys) and analysis_<run>.png. Analysis notes:

• Unit-normalize 4096-dimensional vectors before similarity/clustering (the script already does this);

• Classification/regression are automatically skipped for small samples (protection threshold ≥6 sequences); these analyses are only statistically meaningful after the full 3806 sequences have been run;

• Key cis_enhancers__xxx → category enhancers, region cis; trans_* likewise (modify parse_source to change label dimensions for cis-vs-trans classification).

Development and testing

pixi install          # 或 pip install -e ".[dev]"
pixi run test         # 运行 pytest（全部 mock，不调用真实 API）

Offline tests 91 passed / 4 skipped (skips are live-gated). Coverage: sequence validation, case/whitespace normalization, invalid characters, missing API key, forward request construction, 401/408/429/5xx/timeout, automatic layer-name detection (including the concurrency race regression), variant validation, variant/batch scoring mathematical correctness (independently recomputed against Arc semantics), NPZ decoding (JSON base64 / zip / legacy JSON tensor / <layer>.output key), FASTA sandbox, MCP session integration, script pure functions (pooling/key names), etc.

Real API smoke tests (require a real key, skipped by default). The key is read automatically from .env (Settings.from_env() already loads it):

EVO2_MCP_RUN_LIVE=1 .pixi/envs/dev/bin/python -m pytest tests/test_live_api.py -v -s

Live tests make real requests to the NVIDIA endpoint, verifying: automatic logits layer detection (unembed), real NPZ parsing ((1, seq, 512) float64), evo2_score matching manual recomputation from raw logits, and variant scores.

Project structure

.
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/evo2_mcp/
│   ├── __main__.py      # python -m evo2_mcp 入口
│   ├── config.py        # 环境变量配置
│   ├── sequence.py      # DNA 校验/归一化
│   ├── api_client.py    # HTTP 客户端（retry/backoff/错误分类/响应解码 + layer 自动探测）
│   ├── forward_output.py# NPZ 解码 + likelihood 计算 + embedding 提取
│   ├── fasta.py         # FASTA 解析 + 读取沙箱
│   ├── tools.py         # 5 个 Tool 的实现
│   └── server.py        # MCP server（stdio）
├── scripts/
│   ├── score_fasta.py   # 批量 FASTA 评分 + embedding 提取（每次运行独立 run 文件夹）
│   └── analyze_run.py   # 下游分析：加载/关联 → 聚类/分类/回归 + PCA 图
├── tests/               # pytest（全 mock，91 用例）+ 可选 live test
└── output/              # mode="save" 的 .npz 输出 + run_*/ 运行结果（git 忽略）