Evo 2 MCP Tools

Evo 2 MCP Tools#

The evo2-mcp server exposes Evo 2 as a MCP server, providing tools for genomic sequence analysis. Any MCP-compatible client can use these tools to score, embed, and generate DNA sequences.

Available Tools#

Sequence Scoring#

evo2_mcp.tools.score_sequence(sequence, checkpoint=None, reduce_method='mean')#

Compute log probabilities for DNA sequence under Evo 2 model.

Evaluates the likelihood of a DNA sequence under the Evo 2 language model. Returns the model’s log probability score for the entire sequence, which can be reduced using either mean or sum aggregation.

Parameters:

  • sequence (str) – DNA sequence to score. Should contain standard IUPAC nucleotides (A, C, G, T, N).

  • checkpoint (str | None) – Model checkpoint identifier. If None, uses the default checkpoint. See list_available_checkpoints() for available options.

  • reduce_method (str) – Method for aggregating per-token scores. Must be either “mean” (average log probability across all tokens) or “sum” (sum of all log probabilities).

Returns:

  • checkpoint: The checkpoint identifier used

  • sequence: The normalized input sequence

  • reduce_method: The reduction method applied

  • scores: List of computed score values (typically length 1)

Return type:

Dictionary containing

Raises:

AssertionError – If sequence is empty or reduce_method is not “mean” or “sum”.

Example

>>> scores = score_sequence("ATCGATCG")
>>> print(f"Score: {scores['scores'][0]}")

Sequence Embedding#

evo2_mcp.tools.embed_sequence(sequence, checkpoint=None, layer_name='blocks.2.mlp.l3')#

Return intermediate Evo 2 embeddings for DNA sequence.

Extracts feature representations from a specified layer of the Evo 2 model for a given DNA sequence. The embeddings capture the model’s learned representations and can be used for downstream analysis or as features for other tasks.

Parameters:

  • sequence (str) – DNA sequence to embed. Should contain standard IUPAC nucleotides (A, C, G, T).

  • checkpoint (str | None) – Model checkpoint identifier. If None, uses the default checkpoint. See list_available_checkpoints() for available options.

  • layer_name (str) – Name of the model layer from which to extract embeddings. Common choices include intermediate MLP layers and attention blocks.

Returns:

  • checkpoint: The checkpoint identifier used

  • sequence: The normalized input sequence

  • layer_name: The layer from which embeddings were extracted

  • embedding: 2D list of embedding vectors (shape: [sequence_length, embedding_dim])

Return type:

Dictionary containing

Raises:

AssertionError – If sequence or layer_name are empty strings.

Example

>>> embeddings = embed_sequence("ATCGATCG")
>>> embedding_matrix = embeddings["embedding"]
>>> print(f"Embedding shape: {len(embedding_matrix)} tokens")

Embedding Layer Selection#

evo2_mcp.tools.get_embedding_layers(checkpoint, which='recommended')#

Get available layers for embedding extraction from Evo 2 model.

Returns a list of layer names that can be used to extract sequence embeddings from the specified Evo 2 checkpoint. Different layers encode varying levels of biological abstraction. Larger models tend to have more nuanced representations but require more computational resources. For supervised classification tasks (e.g., variant effect prediction), intermediate layers like Block 20 (40B model) often perform best. For mechanistic interpretability (e.g., SAE training), deeper layers like Layer 26 are commonly used. For probing tasks, top-level layers (e.g., blocks.26 in 7B model) may be optimal.

Parameters:

  • checkpoint (str) – Model checkpoint identifier. See list_available_checkpoints() for options.

  • which (str) – Selection switch. “recommended” returns a curated subset of layers suitable for common downstream tasks; “all” returns every available layer from the model.

Returns:

  • checkpoint: The checkpoint identifier

  • layers: List of layer names available for embedding extraction

  • info: Information about layer selection for different tasks

Return type:

Dictionary containing

Example

>>> layers = get_embedding_layers("evo2_7b")
>>> print(f"Layers (recommended): {layers['layers']}")
>>> layers_all = get_embedding_layers("evo2_7b", which="all")
>>> print(f"Total layers: {len(layers_all['layers'])}")

Sequence Generation#

evo2_mcp.tools.generate_sequence(prompt, checkpoint=None, n_tokens=400, temperature=1.0, top_k=4)#

Generate DNA sequence continuation using Evo 2.

Generates new DNA sequence tokens conditioned on a given prompt sequence using the Evo 2 language model. The generation process uses nucleus sampling (top-k) for controlled diversity.

Parameters:

  • prompt (str) – Starting DNA sequence to condition generation. Should contain standard IUPAC nucleotides (A, C, G, T, N).

  • checkpoint (str | None) – Model checkpoint identifier. If None, uses the default checkpoint. See list_available_checkpoints() for available options.

  • n_tokens (int) – Number of new tokens to generate. Must be a positive integer.

  • temperature (float) – Sampling temperature controlling randomness. Higher values (>1.0) increase diversity; lower values (<1.0) make generation more deterministic. Must be greater than 0.

  • top_k (int) – Number of highest probability nucleotides to sample from at each step. Must be positive. Typical values: 5 (all nucleotides including N), 4 (more constrained).

Returns:

  • checkpoint: The checkpoint identifier used

  • prompt: The normalized input prompt sequence

  • generated_sequence: The newly generated DNA sequence

  • n_tokens: Number of tokens generated

  • temperature: Temperature value used

  • top_k: Top-k value used

Return type:

Dictionary containing

Raises:

AssertionError – If prompt is empty, n_tokens <= 0, temperature <= 0, or top_k <= 0.

Example

>>> result = generate_sequence("ATCGATCG", n_tokens=100, temperature=0.8)
>>> full_sequence = result["prompt"] + result["generated_sequence"]
>>> print(f"Generated sequence: {full_sequence}")

SNP Variant Effect Prediction#

evo2_mcp.tools.score_snp(sequence, alternative_allele, checkpoint=None, reduce_method='mean')#

Score the effect of a SNP mutation at the center position of a DNA sequence.

Computes log probabilities for both the original sequence and the sequence with the center nucleotide replaced by the alternative allele, then returns the delta. Recommended sequence length: max_context - 1 for best performance.

This tool is useful for variant effect prediction, where the score delta indicates how much the mutation changes the model’s likelihood of the sequence. Negative deltas indicate the mutation decreases likelihood; positive deltas increase it.

Parameters:

  • sequence (str) – Reference DNA sequence. Must be at least 3 nucleotides long to have a well-defined center position. Should contain standard IUPAC nucleotides (A, C, G, T, N).

  • alternative_allele (str) – Alternative nucleotide at the center position. Must be a single nucleotide (one of A, C, G, T, N) that differs from the reference nucleotide at the center.

  • checkpoint (str | None) – Model checkpoint identifier. If None, uses the default checkpoint. See list_available_checkpoints() for available options.

  • reduce_method (str) – Method for aggregating per-token scores. Must be either “mean” (average log probability across all tokens) or “sum” (sum of all log probabilities).

Returns:

  • checkpoint: The checkpoint identifier used

  • original_sequence: The input reference sequence (uppercase)

  • mutated_sequence: The sequence with the mutation applied at center position

  • center_position: Index of the mutated position (0-indexed)

  • reference_allele: The original nucleotide at the center position

  • alternative_allele: The alternative nucleotide used

  • reduce_method: The reduction method applied

  • original_score: Log probability score of the reference sequence

  • mutated_score: Log probability score of the mutated sequence

  • score_delta: Difference (mutated_score - original_score). Indicates mutation effect.

Return type:

Dictionary containing

Raises:

AssertionError – If sequence length < 3, alternative_allele is not a single valid nucleotide, sequence contains invalid nucleotides, or alternative_allele matches the reference nucleotide.

Example

>>> result = score_snp("ATCGATCG", "A")  # Center is T, mutate to A
>>> print(f"Score delta: {result['score_delta']}")
>>> print(f"Original: {result['original_sequence']}")
>>> print(f"Mutated: {result['mutated_sequence']}")

Checkpoint Selection#

evo2_mcp.tools.list_available_checkpoints()#

List supported Evo 2 checkpoints with descriptions.

Retrieves all available Evo 2 model checkpoints that can be used for sequence scoring, embedding, and generation. Each checkpoint is described with its size and context length capabilities.

Returns:

  • name: The identifier string for the checkpoint

  • description: Human-readable description of the model specifications

Return type:

List of dictionaries, each containing

Select the appropriate checkpoint based on your constraints and use case:

Checkpoint

Size

Context

Use Case

evo2_7b

7B

1M

General genomic analysis

evo2_40b

40B

1M

Complex analyses (multi-GPU)

evo2_7b_base

7B

8K

General-purpose base model

evo2_40b_base

40B

8K

Base model for large-scale tasks

evo2_1b_base

1B

8K

Fast inference

Hint

The following Evo 2 checkpoints are currently not supported by the official Evo 2 package and therefore not included here: evo2_7b_262k, evo2_7b_microviridae. They will be added to this documentation once official support is available.

Parameters#

Common Parameters#

  • sequence/prompt: DNA sequences using IUPAC nucleotides (A, C, G, T, N)

  • checkpoint: Model checkpoint identifier (optional, defaults to evo2_7b)

  • reduce_method: Aggregation method for scoring: “mean” or “sum”

Generation Parameters#

  • n_tokens: Number of tokens to generate (default: 400)

  • temperature: Sampling temperature; lower values (0.5-0.8) are more deterministic, higher values (1.0+) explore more diversity

  • top_k: Nucleus sampling; typical value is 4

Embedding Parameters#

  • layer_name: Model layer to extract from (default: “blocks.2.mlp.l3”)