Biohub MCP ESM Atlas tools reference

Biohub MCP has six ESM Atlas tools. Each returns structured JSON that your assistant can pass straight to the next tool, and each is marked read-only. The seventh tool, ui_show_protein_structure, is covered in Structure viewer.

Tool	Use it to
`esm_atlas_search_uniprot`	Find UniProt proteins and their sequences.
`esm_atlas_lookup_accession`	Get the sequence for a UniParc, MGnify, or IMG accession.
`esm_atlas_get_protein_details`	See a protein’s ESM Atlas record and strongest SAE features.
`esm_atlas_search_similar_protein_clusters`	Find cluster representatives with similar SAE features.
`esm_atlas_get_cluster_info`	Summarize a cluster representative’s cluster.
`esm_atlas_get_sae_feature_detail`	Explain one SAE feature.

Sequence inputs

Tools that take a sequence expect a raw amino-acid sequence in one-letter codes.

Use the 20 standard residues or X, B, U, Z, or O.
Letters are case-insensitive, and spaces before or after the sequence are removed.
Don’t include a FASTA header, spaces, or line breaks inside the sequence.
The ESM Atlas matches the exact sequence, so a variant or trimmed sequence counts as a different protein.

Any other character returns invalid_input. The server also accepts : and | and passes them to the ESM Atlas unchanged.

Search UniProt

esm_atlas_search_uniprot searches UniProt and returns protein metadata with sequences you can pass to the other tools.

Inputs

Name	Type	Required	Limits	Default
`query`	string	Yes	1 to 500 characters
`size`	integer	No	1 to 6	6

A query shaped like a UniProt accession, such as P42212, is looked up directly. Anything else runs as a UniProt search, so fielded syntax works, for example gene:CDK2 AND organism_id:9606 AND reviewed:true.

Returns

Field	Description
`query_label`	A short label for the query.
`proteins[]`	Matching records, at most `size`.
`proteins[].accession`	UniProt accession.
`proteins[].protein_name`, `gene`, `organism`	Recommended name, first gene name, and scientific name of the organism.
`proteins[].function`	UniProt function text, which can be empty.
`proteins[].sequence`, `sequence_length`	Amino-acid sequence and length. The sequence is `null` when it is longer than 4,000 residues.
`num_results`	Number of records returned.
`total_results`	Total matches UniProt reported.

Resolve an accession

esm_atlas_lookup_accession fetches the sequence for an accession from UniParc, MGnify, or IMG.

Inputs

Name	Type	Required	Limits	Default
`accession`	string	Yes	1 to 128 characters

The tool recognizes these formats:

Database	Format
UniParc	`UPI` followed by 10 hexadecimal characters
MGnify	`MGYP` followed by 12 digits
IMG	A 9 or 10 digit gene ID, or a `Ga0` or `JGI` metagenome gene ID

For example, UPI0000002FB4 is the UniParc entry for GFP. A UniProt accession such as P42212 returns invalid_input. Use esm_atlas_search_uniprot for those.

Returns

Field	Description
`accession`	The accession you sent.
`database`	`uniparc`, `mgnify`, or `img`.
`sequence`, `sequence_length`	Amino-acid sequence and length.

An accession the database doesn’t have, or one without a usable amino-acid sequence, returns not_found. A sequence longer than 4,000 residues returns invalid_input.

Get protein details

esm_atlas_get_protein_details returns a protein’s ESM Atlas record and its ten strongest SAE features.

Inputs

Name	Type	Required	Limits	Default
`sequence`	string	Yes	1 to 4,000 residues

Compute on miss

If the ESM Atlas has the sequence, the tool returns the stored record. If it doesn’t, the ESM Atlas computes SAE features for sequences up to 2,048 residues and sets features_computed_on_miss to true. A longer sequence that misses returns sequence_too_long_for_features. This tool never predicts a structure. To view one, call ui_show_protein_structure with the same sequence.

Returns

Field	Description
`sequence`, `sequence_length`	The normalized sequence and its length.
`accession`, `header`, `source`	ESM Atlas identity, when the sequence is in the ESM Atlas. `source` names the collection, such as `uniparc`.
`sae_features[]`	Up to ten features, strongest first.
`sae_features[].feature_index`	Feature number, 0 to 16,383. Pass it to `esm_atlas_get_sae_feature_detail`.
`sae_features[].label`, `description`	What the feature is thought to represent.
`sae_features[].value`	Activation strength.
`sae_features[].label_reliability`	`high` when `value` is at least 1.0, `moderate` from 0.5, and `low` below 0.5.
`sae_features[].residue_regions[]`	Stretches where the feature is active: `start`, `end`, `peak_residue`, and `mean_activation`.
`ptm`, `mean_plddt`	Confidence of the stored structure, from 0 to 1, when there is one.
`structure_available`	Whether the ESM Atlas has a stored structure.
`structure_can_be_computed`	`true` when the sequence is 700 residues or fewer, so the viewer can predict a structure on a miss.
`features_computed_on_miss`	Whether the features were computed for this request.
`structure_source`, `structure_model`	Where the stored structure came from, when available.
`structure_size_bytes`, `residue_confidence_count`	Size of the stored PDB file and number of per-residue confidence values.
`folded_on_miss`	Always `false` for this tool.

Positions in residue_regions start at 0, while the structure viewer numbers residues from 1, so add 1 to match them.

Find similar protein clusters

esm_atlas_search_similar_protein_clusters compares a sequence’s SAE feature vector with ESM Atlas cluster representatives and returns the closest ones.

Inputs

Name	Type	Required	Limits	Default
`sequence`	string	Yes	1 to 2,048 residues
`top_k`	integer	No	1 to 12	10
`uncharacterized_only`	boolean	No		`false`

Set uncharacterized_only to true to return only clusters with no characterized Pfam annotations.

Behavior

You can get fewer than top_k hits, because the ESM Atlas leaves out matches with a similarity score below 0.5.
The ESM Atlas computes the query’s features if it doesn’t have them.
As a side effect, the ESM Atlas can predict structures for up to six hits that don’t have one yet. The result contains no structures.
Every hit includes its sequence, so the assistant can pass it to the other tools.

Returns

Field	Description
`query_sequence_length`	Length of your sequence.
`hits[]`	Cluster representatives, most similar first.
`hits[].protein_accession`	Representative’s accession.
`hits[].sequence`, `sequence_length`	Representative’s sequence and length.
`hits[].similarity_score`	Cosine similarity of the SAE feature vectors, from 0 to 1.
`hits[].cluster_size`, `protein_name`	Cluster size and name, when available.
`top_features_across_results[]`	Features common across the hits: `feature_index`, `occurrence_count`, and `mean_activation`.
`restricted_count`	Number of hits withheld by ESM Atlas guardrails.

The REST equivalent is similarity search.

Get cluster details

esm_atlas_get_cluster_info summarizes the cluster that a representative sequence belongs to.

Inputs

Name	Type	Required	Limits	Default
`sequence`	string	Yes	1 to 4,000 residues

The sequence must be a cluster representative, such as a hit from esm_atlas_search_similar_protein_clusters. Other sequences, including many well-known UniProt proteins, return not_found. This tool reads stored data only and never computes.

Returns

Field	Description
`accession`, `source`, `protein_name`	Representative’s identity.
`cluster_size`	Number of proteins in the cluster.
`cluster_pct_characterized`	Percentage of members with characterized Pfam annotations, 0 to 100.
`cluster_mean_domain_coverage`	Mean Pfam domain coverage across members, from 0 to 1.
`top_pfam_domains`	Map of Pfam ID to `count` and `name`, or `null`.
`representative_features[]`	Up to ten SAE features with `feature_index`, `label`, `description`, and `value`.
`taxonomy_info`	Lowest common ancestor `rank` and `name`, or `null`.
`top_phyla`	Map of phylum to member count, or `null`.

The REST equivalent is get cluster.

Get SAE feature details

esm_atlas_get_sae_feature_detail explains one of the 16,384 SAE features learned from ESMC.

Inputs

Name	Type	Required	Limits	Default
`feature_index`	integer	Yes	0 to 16,383

Returns

Field	Description
`feature_index`	Feature number.
`label`, `summary`, `description`	Short label and longer interpretations.
`category`	Broad category, such as `Compositional bias`, when available.
`activation_pattern`	Where and how the feature tends to fire, when available.
`exemplar_protein_families`	Example families, when available.
`uniref90_frequency`	How often the feature appears across UniRef90.
`top_swissprot_activations[]`	Up to ten SwissProt proteins with the strongest activation: `uniprot_id` and `activation`.
`decoder_nearest_neighbors[]`	Up to five related feature numbers.

The REST equivalent is get SAE feature.

Errors

A failed call returns a JSON object with a stable code and a message, for example:

{"code":"invalid_input","message":"Unrecognized accession format. Supported databases are UniParc, MGnify, and IMG."}

Code	Returned by	Typical cause
`invalid_input`	All	An input breaks a type, format, or limit.
`not_found`	Lookup, cluster, and feature tools	The accession, cluster, or feature doesn’t exist.
`restricted`	Tools that call the ESM Atlas	ESM Atlas guardrails blocked the request.
`rate_limited`	Tools that call the ESM Atlas	The ESM Atlas asked callers to slow down. The error includes `retry_after_seconds`.
`dependency_unavailable`	All	The ESM Atlas or an external database is unavailable or sent an unusable response.
`indeterminate`	All	The 120-second deadline passed, or the outcome of a compute step is unknown.
`sequence_too_long_for_features`	`esm_atlas_get_protein_details`	A miss longer than 2,048 residues.
`resource_too_large`	All	The complete result is over 6 MiB.
`internal_error`	All	An unexpected server failure.

Troubleshooting explains what to do about each code.

​Sequence inputs

​Search UniProt

​Inputs

​Returns

​Resolve an accession

​Inputs

​Returns

​Get protein details

​Inputs

​Compute on miss

​Returns

​Find similar protein clusters

​Inputs

​Behavior

​Returns

​Get cluster details

​Inputs

​Returns

​Get SAE feature details

​Inputs

​Returns

​Errors

Sequence inputs

Search UniProt

Inputs

Returns

Resolve an accession

Inputs

Returns

Get protein details

Inputs

Compute on miss

Returns

Find similar protein clusters

Inputs

Behavior

Returns

Get cluster details

Inputs

Returns

Get SAE feature details

Inputs

Returns

Errors