# Get cluster info and member hashes for a representative protein Source: https://docs.biohub.ai/api/protein/atlas/clusters openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/clusters/{protein_hash} Look up cluster metadata and member protein hashes for a cluster representative protein identified by its MD5 hash. # Get detailed metadata for a single SAE feature Source: https://docs.biohub.ai/api/protein/atlas/features/detail openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/features/{feature_index} Return all available metadata for one SAE feature: longform description, top activating UniRef90 and SwissProt proteins, decoder nearest neighbors, and activation statistics. # Get Features Source: https://docs.biohub.ai/api/protein/atlas/features/list openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/features Return all SAE features (feature_index, label, description). # ESM Atlas API Source: https://docs.biohub.ai/api/protein/atlas/overview Summary of the ESM Atlas REST endpoints for proteins, clusters, SAE features, similarity search, and batch lookup. The [ESM Atlas](/learn/guides/esm-atlas) is an open-access resource of predicted protein structures and interpretable feature annotations. The ESM Atlas API exposes the same data through REST endpoints at `https://biohub.ai/esm/protein/api/v1alpha1`. Atlas REST endpoints are public and do not require an API key. The API version is `v1alpha1`, so interfaces may change without notice. Most endpoints identify a protein by its `protein_hash`, the MD5 hash that the Atlas uses as the protein's ID. If you start from a UniProtKB accession, call [Resolve UniProt ID](/api/protein/atlas/proteins/uniprot) first to get the `protein_hash`. ## Proteins | Endpoint | Purpose | | - | - | | [Get Protein](/api/protein/atlas/proteins/get) | Return a protein's metadata, amino-acid sequence, and top-activating SAE features. | | [Get Thumbnail](/api/protein/atlas/proteins/thumbnail) | Return a pre-rendered PNG thumbnail of a protein's predicted structure. | | [Resolve UniProt ID](/api/protein/atlas/proteins/uniprot) | Resolve a UniProtKB accession or entry name to its protein record and `protein_hash`. | ## Batch lookup Batch lookup retrieves data for many proteins in one request. Small batches return a zip file directly with status `200`. Large batches return a job handle with status `202`, which you poll until the zip file is ready. | Endpoint | Purpose | | - | - | | [Batch Lookup](/api/protein/atlas/proteins/batch) | Look up multiple proteins by `protein_hash`. | | [Poll Batch Job](/api/protein/atlas/proteins/batch-status) | Check an async batch job and get its zip download URL when it completes. | | [Cancel Batch Job](/api/protein/atlas/proteins/batch-cancel) | Request cancellation of an async batch job. | ## Clusters and similarity | Endpoint | Purpose | | - | - | | [Get Cluster](/api/protein/atlas/clusters) | Return cluster metadata and member protein hashes for a cluster representative protein. | | [Similarity Search](/api/protein/atlas/similarity-search) | Submit an amino-acid sequence and find Atlas proteins with similar SAE feature vectors. | ## SAE features Sparse autoencoder (SAE) features are interpretable signals learned from the ESMC protein language model. | Endpoint | Purpose | | - | - | | [List SAE Features](/api/protein/atlas/features/list) | Return every SAE feature with its index, label, and description. | | [Get SAE Feature](/api/protein/atlas/features/detail) | Return full metadata for one feature, including top activating proteins and activation statistics. | ## Next steps For step-by-step examples that combine these endpoints, see the [Atlas API guides](/learn/tutorials/atlas/overview). To query the Atlas from an AI assistant without writing code, use [Biohub MCP](/biohub-mcp/overview). # Batch protein lookup Source: https://docs.biohub.ai/api/protein/atlas/proteins/batch openapi/metagenomic-atlas-openapi.json POST /esm/protein/api/v1alpha1/proteins/batch Look up multiple proteins by hash. Small batches return a zip file with per-data-type files (200). Large batches return a job handle for async polling (202). # Cancel an async batch protein lookup job Source: https://docs.biohub.ai/api/protein/atlas/proteins/batch-cancel openapi/metagenomic-atlas-openapi.json DELETE /esm/protein/api/v1alpha1/proteins/batch/jobs/{job_id} Request cancellation of an async batch protein lookup job. Cancellation is idempotent: returns 204 whether the job is still pending, already complete, or already cancelled. A job that has already produced results keeps them; subsequent GETs on the job will return the original outcome. Returns 404 if no job with this id is known. # Poll batch protein lookup job status Source: https://docs.biohub.ai/api/protein/atlas/proteins/batch-status openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/proteins/batch/jobs/{job_id} Check the status of an async batch protein lookup. Returns 200 with a zip download URL when complete, 202 when pending, 410 when expired. # Get protein metadata, sequence, and top SAE features Source: https://docs.biohub.ai/api/protein/atlas/proteins/get openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/proteins/{protein_hash} Look up a protein by its MD5 hash and return its metadata, amino acid sequence, and top-activating SAE features. # Get a protein structure thumbnail PNG Source: https://docs.biohub.ai/api/protein/atlas/proteins/thumbnail openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/proteins/{protein_hash}/thumbnail/{thumbnail_type} Stream a pre-rendered protein structure thumbnail PNG. Sub-resource of /proteins/{hash}. The PNG is content-addressed by hash, so the response is cached aggressively (immutable, 1 year). # Resolve a UniProtKB accession to a protein record Source: https://docs.biohub.ai/api/protein/atlas/proteins/uniprot openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/uniprot/{uniprot_id} Look up a UniProtKB accession or entry name (e.g. 'P24941', 'P53_HUMAN') and return its protein record: name, gene, organism, function, sequence, and the Atlas `protein_hash`. UniProtKB only — other accession namespaces (UniParc, MGnify, IMG) return 400. # Search for similar proteins using SAE feature vectors Source: https://docs.biohub.ai/api/protein/atlas/similarity-search openapi/metagenomic-atlas-openapi.json GET /esm/protein/api/v1alpha1/similarity-search Submit an amino acid sequence and find similar proteins in the atlas based on SAE feature vector similarity. # batch_cancel Source: https://docs.biohub.ai/api/protein/models/batch_cancel openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/cancel Cancel a queued item or all queued items of a batch. # Batch folding Source: https://docs.biohub.ai/api/protein/models/batch_folding Predict protein structures and molecular complexes asynchronously with ESMFold2. Use [Batch Submit](/api/protein/models/batch_submit) with `endpoint: "fold"` for protein sequences or `endpoint: "fold_all_atom"` for complexes containing proteins, RNA, DNA, and ligands. Supported models: `esmfold2-2026-05`, `esmfold2-fast-2026-05`, and `esmfold2-2026-05-cutoff-2025`. Each task predicts one structure with your folding configuration. Unlike [fold\_max\_accuracy](/api/protein/models/fold_max_accuracy), these endpoints do not generate an MSA automatically or select the best of multiple predictions. You can supply an MSA to `esmfold2-2026-05` and `esmfold2-2026-05-cutoff-2025`; the fast model ignores MSAs. ## Sequence length The total input length is limited to 4096 tokens. This is the same limit as [fold\_max\_accuracy](/api/protein/models/fold_max_accuracy) and more than the 768 tokens that the on-demand [`fold`](/api/protein/models/fold) and [`fold_all_atom`](/api/protein/models/fold_all_atom) operations accept. Protein residues and RNA/DNA nucleotides count as one token each; ligands and modified residues count by heavy atom. ## Fold protein sequences ```python theme={null} import os from esm.sdk.api import FoldRequest, FoldingConfig from esm.sdk.forge import ForgeBatchClient with ForgeBatchClient( token=os.environ["ESM_API_KEY"], model="esmfold2-fast-2026-05" ) as client: submission = client.fold.submit( requests=[ FoldRequest(sequence="MKTAYIAKQRQISFVKSHFSRQ"), FoldRequest(sequence="GSHMASMTGGQQMGRGS"), ], config=FoldingConfig(include_pae=True), ) print("Batch ID:", submission.batch_id) client.fold.wait(submission) proteins = client.fold.results(submission) ``` Each successful result is an `ESMProtein` with predicted structure and confidence metrics. Use `|` to separate protein chains within a sequence. To name chains instead, pass `chains` as a list of `ChainInput(id, sequence)` objects. Each `FoldRequest` takes either `sequence` or `chains`, not both. ```python theme={null} from esm.sdk.api import ChainInput, FoldRequest request = FoldRequest( chains=[ ChainInput(id="T", sequence="MKTAYIAKQRQISFVKSHFSRQ"), ChainInput(id="B", sequence="GSHMASMTGGQQMGRGS"), ] ) ``` For a multi-chain result, `protein.chains` lists the chain IDs in fold order. `protein.chain_plddt` holds one pLDDT tensor per chain with separator slots removed. Compute per-chain confidence from `chain_plddt` rather than indexing `plddt`, which keeps a NaN slot at each chain separator. For molecular complexes, use `client.fold_all_atom` with `FoldAllAtomRequest`; successful results are `MolecularComplexResult` objects. See [Fold all atom](/api/protein/models/fold_all_atom) for input construction. Both handlers also provide `async_submit`, `async_wait`, `async_results`, and `async_run`. Save the returned batch ID before waiting so you can recover results later. See the [Batch API overview](/api/protein/models/batch_overview) for failures, cancellation, and result retention. # batch_list Source: https://docs.biohub.ai/api/protein/models/batch_list openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/list Read batch status counts and optionally page through its item records. # Batch API Source: https://docs.biohub.ai/api/protein/models/batch_overview Submit inference jobs, track their progress, and retrieve results asynchronously. The Batch API supports larger and longer-running asynchronous workloads. Submit inputs, poll the batch, then retrieve each completed item's result. | Operation | Purpose | | - | - | | [Submit](/api/protein/models/batch_submit) | Queue inputs and return a batch ID. | | [List](/api/protein/models/batch_list) | Read batch status, counts, and pages of items. | | [Status](/api/protein/models/batch_status) | Read one task and retrieve its result and artifact URLs. | | [Cancel](/api/protein/models/batch_cancel) | Cancel queued tasks. | ## Submit inputs Choose the inference operation with `endpoint` and put its inputs in `payload`. Each payload entry becomes a task. | Endpoint | One payload entry is | | - | - | | [`fold`](/api/protein/models/batch_folding) | Protein structure prediction with ESMFold2. | | [`fold_all_atom`](/api/protein/models/batch_folding) | Molecular-complex prediction with ESMFold2. | | [`fold_max_accuracy`](/api/protein/models/fold_max_accuracy) | Maximum-accuracy molecular-complex prediction with ESMFold2. | | [`design_binder`](/api/protein/models/design_binder) | Run binder design trajectories. | Each item costs GPU time, so each endpoint caps how many items you can queue. See [Limits](#limits). ```bash theme={null} curl https://biohub.ai/api/v1/batch/submit \ -H "Authorization: Bearer $BIOHUB_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "endpoint": "fold", "payload": [ { "model": "esmfold2-fast-2026-05", "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ", "include_pae": true } ] }' ``` Save `data.batch_id` from the response. A one-item batch also returns `data.task_id`. Task IDs append a zero-padded index, such as `-00000`. For repeated payloads, ordering is by repeat first, then position within `payload`. ## Retry a submission API-key clients can add an optional lowercase UUIDv4 `submission_id` to any supported batch request. Generate the ID once and save it with the request before submitting. It becomes the `batch_id`. After a timeout or uncertain response, resend the same request with the same ID. An exact replay returns the existing batch with `data.replayed: true`, without queuing more work. Without `submission_id`, each submission creates a new batch. ## Limits Each endpoint caps the items in one submission and the items one user can submit over a rolling window. A submission's item count is the `payload` length times `repeat`. | Limit | `fold` and `fold_all_atom` | `fold_max_accuracy` | `design_binder` | | - | - | - | - | | Items per submission | 2000 | 10 | 256 | | Items per user per rolling window | 5000 per day for each endpoint | 10 per day | 5000 per hour | Every fold endpoint accepts inputs up to 4096 tokens, compared with 768 for the on-demand [`fold`](/api/protein/models/fold) and [`fold_all_atom`](/api/protein/models/fold_all_atom) operations. A submission above the per-submission limit returns `400`. The rolling quota counts every item you submitted in the window, including items that later failed. If a submission would exceed the quota, the API rejects the entire submission with `429`. The `Retry-After` header gives the number of seconds until capacity is available. The `fold` and `fold_all_atom` quotas each count items across all three ESMFold2 models. `fold` and `fold_all_atom` also allow at most 20 submissions and 1,000,000 tokens per minute for each model. `design_binder` also allows at most 10 submissions per minute. A compute grant doubles the rolling quotas and the per-minute limit, but not the per-submission limit. Credit checks apply separately. ## Track progress Poll [List](/api/protein/models/batch_list) with the saved `batch_id`: ```bash theme={null} curl https://biohub.ai/api/v1/batch/list \ -H "Authorization: Bearer $BIOHUB_API_KEY" \ -H "Content-Type: application/json" \ -d '{"batch_id": ""}' ``` The aggregate batch state is `in_progress`, `done`, `failed`, or `cancelled`. An aggregate `done` means all tasks are terminal; some or all tasks may have failed. A cancelled batch can still contain running tasks. | Task state | Meaning | | - | - | | `queued` | Waiting to start. | | `in_progress` | Processing has started. | | `done` | A result is available. | | `failed` | Processing failed. Read the task's error. | | `cancelled` | Cancelled before processing started, by you or by the 24-hour queue limit. | `counts` covers the whole batch and omits states with zero items. Set `include_responses: true` to retrieve an item page, then follow the returned `cursor` until it is null. The default page size is 100 and the maximum is 1000. A full final page can require one additional empty-page request. A `status` filter narrows the item page, while counts remain batch-wide. Tasks that have not started 24 hours after the batch was submitted are cancelled and will not be charged, while tasks already running finish normally. Status and List return this deadline as `data.expires_at`. ## Retrieve results Call [Status](/api/protein/models/batch_status) with a `task_id` from the submission response or an item page: ```bash theme={null} curl https://biohub.ai/api/v1/batch/status \ -H "Authorization: Bearer $BIOHUB_API_KEY" \ -H "Content-Type: application/json" \ -d '{"task_id": ""}' ``` When the task is `done`, `data.response` contains an inline result object, inline text, or a signed URL to download it, depending on the endpoint. For `design_binder`, it is an inline [design record](/api/protein/models/design_binder#result), and `data.artifacts.structure` is a signed PDB download of the complex. Other outputs, when present, are signed URLs in `data.artifacts`, keyed by artifact name. List responses can include inline results but omit artifact URLs. `response_available: true` indicates an externally stored result. Download signed URLs without the Biohub bearer token. Read status again to refresh expired URLs. When present, `data.artifacts_expire_in` gives the shortest artifact URL lifetime in seconds. ## Result retention Results are kept for 31 days after the batch is submitted, after which they are deleted. Status and List return the deadline as `data.results_expire_at`. After that, Status returns `410` and List still reports each item's `status` but omits `response`, `response_available`, and `error`. ## Responses and failures A successful HTTP operation returns this envelope: ```json theme={null} {"status": "success", "data": {}, "request_id": ""} ``` Route errors carry `message` instead: ```json theme={null} {"status": "error", "message": "Batch not found", "request_id": ""} ``` Authentication failures can use `error` instead of `message`; handle both shapes. Retain `request_id` when reporting a failed call. The envelope's `status` describes the HTTP operation, while `data.status` describes the job. An HTTP `200` can report a failed task; inspect `data.error` on the status response. Failure to read status does not mean the task failed. Passing a batch ID to Status returns `404` with instructions to use List or an item ID. ## Cancel [Cancel](/api/protein/models/batch_cancel) accepts exactly one of `task_id` or `batch_id`. It affects queued tasks only. Running tasks continue and retain their usage charges. A batch with no cancellable work returns `409`; cancelling an already cancelled batch succeeds. # batch_status Source: https://docs.biohub.ai/api/protein/models/batch_status openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/status Read one batch item's status, result, and artifact URLs. # batch_submit Source: https://docs.biohub.ai/api/protein/models/batch_submit openapi/biohub-platform-batch-openapi.json POST /api/v1/batch/submit Queue inference and receive a batch ID. # decode Source: https://docs.biohub.ai/api/protein/models/decode openapi/biohub-platform-openapi.json POST /api/v1/decode (ESM3, ESMC) Decodes tokens sequence, structure, or function annotations # design_binder Source: https://docs.biohub.ai/api/protein/models/design_binder Fields of a design_binder item submitted to the Batch API, and the record it returns. Use [Batch Submit](/api/protein/models/batch_submit) with `endpoint: "design_binder"` and one or more items in `payload`. One item is one design trajectory: the service picks a starting binder, folds it with the target, and descends a distogram loss. There is no synchronous design operation, and an item does not name a model. See the [Batch API overview](/api/protein/models/batch_overview) for submission, polling, and downloads. ## Limits and validation | Constraint | Value | | - | - | | Target plus binder | At most 680 residues. | | Target chains | At most 26. | | Hotspots | Nonempty list of valid chain-local addresses. | The per-submission ceiling, the hourly quota, and the per-minute submission limit are listed under [Batch API limits](/api/protein/models/batch_overview#limits). The target must leave room for the longest binder the deployed format configuration can produce. Worker configuration can impose a smaller target limit. Read the allowed length from the validation error rather than assuming the full complex budget is available to the target. The recipe steers its losses toward the hotspots and measures the contacts the binder reaches. The service ignores unknown design-payload fields, so a caller-supplied `label`, recipe version, binder length, or trajectory time limit does not configure the run. The batch handler checks the envelope and limits; scientific payload validation occurs in the worker. As a result, an item can fail with a validation error even after a `200` submission response. ## Request One `payload` entry holds these fields. Supply the target through `target_chains` or `target_sequence`, not both. | Field | Type | Description | | - | - | - | | `target_chains` | array or null | The target as named chains. A hotspot can then name a chain id rather than a position in one exact string. | | `target_sequence` | string or null | The target as one string, where a vertical bar separates chains. The server names the chains `A`, `B`, `C`, and the returned structure uses those labels. | | `hotspots` | array | Required. The target residues the binder must contact, each addressed per chain. They steer the design and they score it. | | `binder_format` | string | One of `minibinder`, `vhh`, `scfv`, or `antibody`. | | `seed` | integer | Base seed. In a batch, the service adds the item index to it, so each trajectory starts from a different point. The sum wraps at 2147483647. | | `potential_sequence_of_concern` | boolean | Disclose potential sequences of concern. For approved users, such sequences skip additional safety filtering. | ## Result [List batch items](/api/protein/models/batch_list) returns design records inline when you set `include_responses: true`. [Read a task](/api/protein/models/batch_status) returns one record in `data.response` and a signed PDB download in `data.artifacts.structure`. List responses never include those artifact URLs. | Field | Type | Description | | - | - | - | | `created` | string | The time the service created the record. | | `potential_sequence_of_concern` | boolean | The returned sequence can be of potential concern. | | `tokens_used` | integer | The tokens the item consumed. | | `warning_messages` | array or null | Warnings the service returned. | | `target_sequence` | string | The target the trajectory designed against. | | `hotspots` | array or null | The requested hotspots with the residue each one landed on, as `{chain, position, residue}`. | | `target_chain_ids` | array or null | The caller's target chain IDs in target order, or the generated `A`, `B`, `C` IDs. The PDB artifact uses positional chain labels, which can differ from these IDs. | | `binder_format` | string | The binder format the trajectory ran. | | `seed` | integer | The seed of this trajectory. `repeat` offsets the seed by the item index. | | `binder_sequence` | string or null | The designed binder. Absent unless `generation_metadata.stopped_reason` is `completed`. | | `self_scored` | object or null | The design models' scores for the final complex. | | `self_scored_by_replica` | array or null | The same scores per replica, in the order of `generation_metadata.fold_replicas`. | | `generation_metadata` | object or null | What ran: recipe version, models, schedule, steps, and stop reason. | | `accounting` | object or null | The compute the trajectory used. | `self_scored` holds: | Field | Type | Description | | - | - | - | | `ptm` | number or null | Predicted TM-score of the complex. | | `interface_ptm` | number or null | Predicted TM-score of the interface. | | `plddt_mean` | number or null | Mean pLDDT of the complex. | | `hotspot_min_distances_angstrom` | array or null | Per hotspot, the binder's closest heavy-atom approach, in the order the caller gave the hotspots. | Each entry of `self_scored_by_replica` holds `ptm`, `interface_ptm`, and `plddt_mean`, plus: | Field | Type | Description | | - | - | - | | `model` | string | The checkpoint that produced these numbers. | | `step` | integer or null | The last step this replica folded. | `generation_metadata` holds: | Field | Type | Description | | - | - | - | | `recipe_version` | integer | The recipe configuration this design ran under. A request cannot ask for a version. | | `fold_model` | string or null | The checkpoint that drove the fold, when the trajectory used one. | | `fold_replicas` | array or null | The folding replicas the trajectory alternated between. | | `fold` | object or null | `num_recycles` and `num_sampling_steps`. | | `schedule` | object or null | Steps per stage: `warm_up`, `softmax_annealing`, `temperature_annealing`, and `straight_through`. | | `steps_run` | integer | The steps the trajectory ran. | | `stopped_reason` | string | `completed` or `error`. A trajectory runs its configured steps or raises; there is no wall-clock stop. | `accounting` holds `gradient_steps` and `gpu_seconds`. ### Interpretation `self_scored` is the design models' assessment of the complex they optimized. It comes from the models the trajectory spent every step optimizing against, so it is inflated. Rank a population with it, then judge the winners with independent folds of your own. `self_scored_by_replica` preserves per-model disagreement that an average can hide. `self_scored.hotspot_min_distances_angstrom` follows the requested hotspot order. A null distance is missing evidence, not a passing contact. Check the echoed hotspot residue letters against your intended crop. PDB numbering and chain labels can differ from request addresses, so retain the mapping you submitted. `generation_metadata` records the recipe version, models, schedule, steps run, and stop reason. It describes what ran; it does not let the caller select a historical recipe. `accounting` reports gradient steps and GPU seconds, while the task's `tokens_used` reports billed usage when available. ```json DesignBinderRequest theme={null} { "endpoint": "design_binder", "payload": [ { "target_chains": [ { "id": "A", "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ" } ], "hotspots": [{ "chain": "A", "position": 12 }], "binder_format": "minibinder", "seed": 0 } ] } ``` ```json DesignBinderResponse theme={null} { "created": "2026-10-15T21:54:24Z", "tokens_used": 33, "target_sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQ", "target_chain_ids": ["A"], "hotspots": [{ "chain": "A", "position": 12, "residue": "I" }], "binder_format": "minibinder", "seed": 0, "binder_sequence": "SLEELRKRIEELERKLGSGSGDPELLRRLEELLRRLEELLK", "self_scored": { "ptm": 0.81, "interface_ptm": 0.73, "plddt_mean": 0.87, "hotspot_min_distances_angstrom": [3.6] }, "generation_metadata": { "recipe_version": 3, "fold": { "num_recycles": 1, "num_sampling_steps": 2 }, "steps_run": 150, "stopped_reason": "completed" }, "accounting": { "gradient_steps": 150, "gpu_seconds": 221.4 } } ``` # encode Source: https://docs.biohub.ai/api/protein/models/encode openapi/biohub-platform-openapi.json POST /api/v1/encode (ESM3, ESMC) Tokenize sequence, structure, or function annotations # fold Source: https://docs.biohub.ai/api/protein/models/fold openapi/biohub-platform-openapi.json POST /api/v1/fold (ESM3, ESMFold2) Folds proteins. Defaults to esmfold2-fast-2026-05 if no model is given On this operation the ESMFold2 models accept inputs up to 768 tokens. For asynchronous ESMFold2 predictions, and for inputs up to 4096 tokens, use [Batch folding](/api/protein/models/batch_folding) with `endpoint: "fold"`. # fold_all_atom Source: https://docs.biohub.ai/api/protein/models/fold_all_atom openapi/biohub-platform-openapi.json POST /api/v1/fold_all_atom (ESMFold2) Folds molecular complexes containing proteins, dna, rna, and ligands. Defaults to esmfold2-fast-2026-05 if no model is given This operation accepts inputs up to 768 tokens. For asynchronous predictions, and for inputs up to 4096 tokens, use [Batch folding](/api/protein/models/batch_folding) with `endpoint: "fold_all_atom"`. # fold_max_accuracy Source: https://docs.biohub.ai/api/protein/models/fold_max_accuracy Submit fold_max_accuracy items to the Batch API to predict molecular complexes with a generated MSA, five seeded folds, and a 4096-token input limit. Use [Batch Submit](/api/protein/models/batch_submit) with `endpoint: "fold_max_accuracy"` and one or more inputs in `payload`. Each item must name `esmfold2-2026-05-cutoff-2025` as its model. This operation is available on Biohub's Batch API. The schema below describes one payload entry. See the [Batch API overview](/api/protein/models/batch_overview) for submission, polling, and downloads. ## Inputs and limits Supply a molecular complex through `all_atom_input` with protein, RNA, DNA, or ligand entries. The total input length is limited to 4096 tokens. Protein residues and RNA/DNA nucleotides count as one token each; ligands and modified residues count by heavy atom. A submission holds at most 10 items, and each user can submit at most 10 items per rolling day. See [Batch API limits](/api/protein/models/batch_overview#limits) for how the quota is counted. The service generates its own MSA by searching UniRef30 and ColabFold with the following settings: * `max_prefilter` = 100,000 * `max_accept` = 10,000 * `diff` = 3,000 * `expand_diff` = 3,000 It then runs 5 folds with 5 different seeds and selects the best predicted structure. The supported output options are `include_pae`, `include_pair_chains_iptm`, and `include_embeddings`. ## Python SDK Use `FoldMaxAccuracyRequest` to specify each item's input and optional config. The SDK selects the model automatically. ```python theme={null} import os from esm.sdk.api import FoldMaxAccuracyConfig, FoldMaxAccuracyRequest from esm.sdk.forge import ForgeBatchClient from esm.utils.structure.input_builder import ProteinInput, StructurePredictionInput inputs = [ StructurePredictionInput(sequences=[ProteinInput(id="A", sequence=sequence)]) for sequence in ("MKTAYIAKQRQISFVKSHFSRQ", "GSHMASMTGGQQMGRGS") ] with ForgeBatchClient(token=os.environ["ESM_API_KEY"]) as client: submission = client.fold_max_accuracy.submit( config=FoldMaxAccuracyConfig(include_pae=True), requests=[ FoldMaxAccuracyRequest(all_atom_input=inputs[0]), FoldMaxAccuracyRequest( all_atom_input=inputs[1], config=FoldMaxAccuracyConfig(include_embeddings=True), ), ], ) print("Batch ID:", submission.batch_id) client.fold_max_accuracy.wait(submission) results = client.fold_max_accuracy.results(submission) ``` The first request inherits the shared config and includes PAE. The second request replaces the shared config and includes embeddings without PAE. An omitted or `None` request config uses the shared config. The SDK doesn't merge config fields. # forward_and_sample Source: https://docs.biohub.ai/api/protein/models/forward_and_sample openapi/biohub-platform-openapi.json POST /api/v1/forward_and_sample (ESM3) Performs one inference step and samples output tokens # generate Source: https://docs.biohub.ai/api/protein/models/generate openapi/biohub-platform-openapi.json POST /api/v1/generate (ESM3) Generates an output track conditioned on inputs # generate_tensor Source: https://docs.biohub.ai/api/protein/models/generate_tensor openapi/biohub-platform-openapi.json POST /api/v1/generate_tensor (ESM3) Generates an output track conditioned on inputs. Accepts and returns raw tokens. # inverse_fold Source: https://docs.biohub.ai/api/protein/models/inverse_fold openapi/biohub-platform-openapi.json POST /api/v1/inverse_fold (ESM3) Inverse folds proteins. Defaults to esm3-open-2024-03 if no model is given # logits Source: https://docs.biohub.ai/api/protein/models/logits openapi/biohub-platform-openapi.json POST /api/v1/logits (ESM3, ESMC) Performs one inference step and returns logits, embeddings, and SAE features (ESMC only). # Response formats and payload size Source: https://docs.biohub.ai/api/protein/models/response-formats Choose JSON or binary responses for protein model APIs. Protein model APIs return JSON by default. Supported endpoints also offer opt-in Python pickle responses, which can reduce payload size for tensors and arrays. The `esm` Python SDK requests pickle automatically on these endpoints and decodes the response for you. ## Supported endpoints JSON and pickle responses are available for: | Operation | Endpoints | | - | - | | Tokenization and decoding | [encode](/api/protein/models/encode), [decode](/api/protein/models/decode) | | Generation and sampling | [generate](/api/protein/models/generate), [generate\_tensor](/api/protein/models/generate_tensor), [forward\_and\_sample](/api/protein/models/forward_and_sample) | | Representations | [logits](/api/protein/models/logits) | | Structure prediction and inverse folding | [fold](/api/protein/models/fold), [inverse\_fold](/api/protein/models/inverse_fold) | [fold\_all\_atom](/api/protein/models/fold_all_atom) uses dedicated compact serialization for its molecular-complex payload and does not negotiate pickle responses. ## Choose a format for direct API calls Keep the request body as JSON with `Content-Type: application/json` for either response format. Use the `Accept` header to select the response format. ### JSON Request JSON when you need a language-independent response: ```http theme={null} Accept: application/json ``` The response has `Content-Type: application/json`. Array values are represented as JSON arrays. Omitting `Accept` also returns JSON. ### Pickle Request pickle with a JSON fallback: ```http theme={null} Accept: application/vnd.evolutionaryscale.pickle, application/json ``` A pickle response has `Content-Type: application/vnd.evolutionaryscale.pickle` and contains a pickled response dictionary. Array fields can retain PyTorch tensors or NumPy arrays instead of being converted to lists. Read the response's `Content-Type` before decoding it; the Python SDK handles this automatically. ## HTTP compression Pickle determines how response data is serialized. HTTP gzip compression reduces the size of those serialized bytes and is supported for both JSON and pickle. To allow gzip responses, send: ```http theme={null} Accept-Encoding: gzip ``` Use the response's `Content-Encoding` header to determine whether decompression is needed. The Python SDK's HTTP clients handle decompression automatically. Payload savings depend on the data. Large coordinate or embedding arrays benefit from binary representation, while pickle's object metadata can make small responses larger than JSON. # Biohub MCP ESM Atlas tools Source: https://docs.biohub.ai/biohub-mcp/esm-atlas-tools Look up what the ESM Atlas knows about a protein through Biohub MCP: find its sequence, its SAE features, similar proteins, and their clusters. The ESM Atlas is is a free resource that provides predicted 3D structures from ESMFold2 and interpretable feature annotations, such as function, from the ESMC language model for over a billion proteins. Ask your AI agent questions about proteins through the [ESM Atlas](/learn/guides/esm-atlas), and Biohub MCP looks it up and finds the proteins most like it. To see the structure of a selected protein, use the [structure viewer](/biohub-mcp/structure-viewer), and to obtain structure files and more detailed structure information, see [Get more from the ESM Atlas API](#get-more-from-the-esm-atlas-api). ## Understanding SAE features The ESM Atlas describes each protein by its SAE features: patterns that the [ESMC](/models/esmc) protein language model picks up in sequences, such as a catalytic motif or a transmembrane helix. A sparse autoencoder (SAE) pulled 16,384 of these patterns out of ESMC, and each one has a number, a label, and a strength for your protein, as [Understanding SAE features](/learn/guides/esm-atlas#understanding-sae-features) explains. ## What you can ask Ask in your own words, and your agent picks the tools and passes each result to the next step in the process. For example: What does the ESM Atlas know about PETase from Ideonella sakaiensis? Explain its three strongest SAE features and where in the sequence each one is most active. What does the ESM Atlas know about PETase from Ideonella sakaiensis? Explain its three strongest SAE features and where in the sequence each one is most active. Find the ESM Atlas cluster closest to human hemoglobin alpha and summarize it: how big it is, how well characterized it is, its Pfam domains, and its most common phyla. Find the ESM Atlas cluster closest to human hemoglobin alpha and summarize it: how big it is, how well characterized it is, its Pfam domains, and its most common phyla. Find proteins in the ESM Atlas that resemble PETase from Ideonella sakaiensis but come from clusters with no characterized Pfam domains, and name three SAE features they all share. Find proteins in the ESM Atlas that resemble PETase from Ideonella sakaiensis but come from clusters with no characterized Pfam domains, and name three SAE features they all share. You can use a sequence or an accession number instead of a protein name in any of these prompts. ## Which tools your assistant uses | When you ask to | Your assistant uses | | - | - | | Look up a protein you named, or its UniProt accession | [`esm_atlas_search_uniprot`](#search-uniprot), which returns matching UniProt entries with their sequences. | | Look up a UniParc or MGnify accession | [`esm_atlas_lookup_accession`](#resolve-an-accession), which returns its sequence. | | See what the ESM Atlas knows about a protein | [`esm_atlas_get_protein_details`](#get-protein-details), which returns its ESM Atlas record, the confidence of its stored structure when there is one, and up to ten of its strongest SAE features, each with its label and description. | | Find similar proteins | [`esm_atlas_search_similar_protein_clusters`](#find-similar-protein-clusters), which returns up to 12 cluster representatives with the closest SAE features, optionally only from clusters with no characterized Pfam domains. | | Learn about a similar protein's cluster | [`esm_atlas_get_cluster_info`](#get-cluster-details), which summarizes the cluster of a similarity search hit: its size, Pfam domains, and taxonomy. | | Go deeper on one SAE feature | [`esm_atlas_get_sae_feature_detail`](#get-sae-feature-details), which explains the feature and lists the SwissProt proteins where it is strongest. | | See the structure in 3D | `ui_show_structure`, which opens an interactive viewer. Viewing a single protein structure is free, while viewing complexes requires the use of [folding tools](/biohub-mcp/folding-tools) and is billed to your Biohub account. | | Fold a protein or score mutations | The [folding tools](/biohub-mcp/folding-tools) or the [mutation scoring tools](/biohub-mcp/mutation-scoring-tools), which are billed to your Biohub account. | ## How a lookup works **1. Your AI agent gets the sequence** When you name a protein or give a UniProt accession, your AI agent looks up its sequence with `esm_atlas_search_uniprot`. For a UniParc or MGnify accession, it uses `esm_atlas_lookup_accession`. You can also directly input a protein sequence. **2. The ESM Atlas looks for the exact sequence first** If the ESM Atlas has the exact sequence, you see protein details from the stored record. A variant or a trimmed sequence counts as a new sequence. **3. A new sequence gets its features computed** If the ESM Atlas doesn't have it, protein details and the similarity search compute its SAE features for this request, for sequences of up to 2,048 residues. **4. Similar proteins come from clusters** The ESM Atlas groups proteins into [clusters](/learn/guides/esm-atlas#what-is-a-cluster) by their SAE features, not by sequence identity. One protein, the representative, stands for each cluster. The similarity search compares your protein's features with each representative and returns the closest ones, each with a sequence your agent can pass to the other tools. Cluster details work only for a cluster representative, such as a similarity search hit, and compute nothing. Any other sequence, including many well-known UniProt proteins, returns `not_found`. > [!TIP] > > A name can match several UniProt entries. > Add the organism, as in "PETase from *Ideonella sakaiensis*", or give the UniProt accession. > Your assistant can tell you which entry it used. ## Read the results | Result | What it means | Returned by | | - | - | - | | SAE feature `value` | How strongly the feature is active in the protein, scaled per feature so values compare across proteins. Its `label_reliability` follows from `value` alone: `high` at 1.0 or more, `moderate` from 0.5, and `low` below 0.5. A low value means the feature is barely active, so its label says little about your protein. | Protein details | | `residue_regions` | Up to ten stretches where a feature is most active, strongest first. Positions start at 0, so add 1 to match UniProt and the structure viewer. | Protein details | | `similarity_score` | How alike two proteins' SAE feature profiles are, from 0 to 1. Hits below 0.5 are left out. It does not compare similarity between sequences. | Similarity search | | `cluster_pct_characterized` | The percentage of a cluster's members that match a Pfam domain with a known function. 0 means that there is no member which matches a domain. | Cluster details | | `ptm`, `mean_plddt` | Confidence of the stored predicted structure, from 0 to 1, as [Read the scores](/biohub-mcp/folding-tools#read-the-scores) explains. Often `null`, even for well-known proteins, because many have no stored structure. | Protein details | For example, PETase's strongest feature is feature 11080, labeled "AB hydrolase H-G-x-D motif", with a `label_reliability` of `high`. Its strongest region has `start` 198 and `end` 205, which is residues 199 to 206 in UniProt numbering, ending at Asp206, one of PETase's catalytic residues. Feature labels describe what a feature tends to capture, not an experimental annotation of your protein. ESM Atlas structures are predictions, not experimental structures. ## Get more from the ESM Atlas API The ESM Atlas tools return summaries, so the results stay small enough for your assistant to read. For full data, call the [ESM Atlas API](/api/protein/atlas/overview), which does not require an API key: | You need | Use | | - | - | | A stored structure's PDB file, per-residue pLDDT, or per-residue feature activations | [Get protein](/api/protein/atlas/proteins/get) | | Up to 100 SAE features, or chosen features by index | [Get protein](/api/protein/atlas/proteins/get), with `topk_features` or `feature_indices` | | Up to 100 similar proteins, or a different similarity cutoff | [Similarity search](/api/protein/atlas/similarity-search), with `topk_results` and `min_similarity` | | The hashes of a cluster's members, to pass to batch lookup | [Get cluster](/api/protein/atlas/clusters) | | Data for many proteins at once | [Batch lookup](/api/protein/atlas/proteins/batch) | | Every SAE feature's label and description | [List SAE features](/api/protein/atlas/features/list) | Most endpoints identify a protein by its `protein_hash` instead of its sequence, as the [API overview](/api/protein/atlas/overview) explains. ## Sequences Tools that take a `sequence` expect a raw amino-acid sequence in one-letter codes. * Use the 20 standard amino acids or `X`, `B`, `U`, `Z`, or `O`. * Letters are case-insensitive, and whitespace before or after the sequence, including line breaks, is removed. * Don't include a FASTA header, or spaces or line breaks inside the sequence. `:` and `|` are also accepted, but they stay in the sequence and change which ESM Atlas record matches, so leave them out of a single protein. Any other character returns `invalid_input`. ## Search UniProt `esm_atlas_search_uniprot` searches UniProt and returns protein records with sequences you can pass to the other tools. ### Inputs | Input | Description | | - | - | | `query` (required) | Free text, such as `PETase Ideonella sakaiensis`, or UniProt query syntax, such as `gene:CDK2 AND organism_id:9606 AND reviewed:true`, up to 500 characters. A UniProt accession, such as `P42212`, or an entry name, such as `HBA_HUMAN`, is looked up directly. | | `size` | How many entries to return, from 1 to 6. Defaults to `6`. | * A search that matches nothing returns an empty `proteins` list, not an error. * A direct match on an accession or entry name returns that entry, whatever `size` is. An accession or entry name that UniProt doesn't have runs as a text search instead. * An accession that UniProt has deleted returns one entry with a `null` name and sequence. ### Results | Field | Description | | - | - | | `query_label` | A label of up to 80 characters made from the query with UniProt syntax removed, or `null`. | | `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 a UniParc or MGnify accession. ### Inputs | Input | Description | | - | - | | `accession` (required) | One accession of up to 128 characters, in one of the formats below. | | Database | Format | | - | - | | UniParc | `UPI` followed by 10 hexadecimal characters, such as `UPI0000002FB4`, the UniParc entry for GFP. | | MGnify | `MGYP` followed by 12 digits. | Other formats, including UniProt accessions such as `P42212`, return `invalid_input`; [`esm_atlas_search_uniprot`](#search-uniprot) looks up UniProt accessions. > [!NOTE] > > Looking up an MGnify accession often returns `not_found`, even for accessions the ESM Atlas returns. MGnify only returns sequences for the representative protein of each cluster in its latest release, and its clusters are different from ESM Atlas clusters. Paste the sequence instead. A similarity search hit already includes its sequence, so there is no need to look up its accession. ### Results | Field | Description | | - | - | | `accession` | The accession you sent, with surrounding spaces removed. | | `database` | `uniparc` or `mgnify`. | | `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 up to ten of its strongest SAE features. ### Inputs | Input | Description | | - | - | | `sequence` (required) | One protein of 1 to 4,000 residues, as [Sequences](#sequences) describes. | 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 of up to 2,048 residues, and `features_computed_on_miss` is `true`. A longer sequence that isn't in the ESM Atlas returns `sequence_too_long_for_features`. This tool never predicts a structure; to predict and view one, use [`ui_show_structure`](/biohub-mcp/structure-viewer) with the same sequence, for up to 700 residues. ### Results | Field | Description | | - | - | | `sequence`, `sequence_length` | The normalized sequence and its length. | | `accession`, `header`, `source` | The protein's ESM Atlas accession, header, and source collection, when the sequence is in the ESM Atlas. The collection isn't always UniProt; `source` names it, such as `uniparc` or `img_m`. | | `sae_features[]` | Up to ten features, strongest first, with the fields below. | | `ptm`, `mean_plddt` | Confidence of the stored structure, as [Read the results](#read-the-results) explains. | | `structure_available` | Whether the ESM Atlas has a stored structure. | | `structure_can_be_computed` | `true` when the sequence is 700 residues or fewer, the longest the structure viewer predicts when the ESM Atlas has no stored structure. It checks length only. | | `features_computed_on_miss` | Whether the features were computed for this request. | | `structure_size_bytes`, `residue_confidence_count` | Size of the stored PDB file and number of per-residue confidence values. | | `structure_source`, `structure_model`, `folded_on_miss` | Fixed for this tool: `structure_source` is `atlas` with a stored structure and `null` without one, `structure_model` is `null`, and `folded_on_miss` is `false`. | Each entry in `sae_features` has: | Field | Description | | - | - | | `feature_index` | Feature number, 0 to 16,383. Pass it to [`esm_atlas_get_sae_feature_detail`](#get-sae-feature-details). | | `label`, `description` | What the feature is thought to represent. | | `value` | Activation strength, as [Read the results](#read-the-results) explains. | | `label_reliability` | `high`, `moderate`, or `low`, set by `value`. | | `residue_regions[]` | Up to ten stretches where the feature is most active, strongest first: `start`, `end`, `peak_residue`, and `mean_activation`. Positions start at 0, and `end` is included. `mean_activation` is a raw activation, on a different scale from `value`. | ## Find similar protein clusters `esm_atlas_search_similar_protein_clusters` compares a sequence's SAE features with ESM Atlas cluster representatives and returns the closest ones. ### Inputs | Input | Description | | - | - | | `sequence` (required) | One protein of 1 to 2,048 residues, as [Sequences](#sequences) describes. | | `top_k` | The most representatives to return, from 1 to 12. Defaults to `10`. | | `uncharacterized_only` | `true` returns only clusters with no characterized Pfam domains. Defaults to `false`. | * You can get fewer than `top_k` hits, because the ESM Atlas leaves out matches scoring below 0.5 and withholds hits are restricted by its [guardrails](/learn/guides/esm-atlas#guardrails) . * The ESM Atlas can also predict structures for up to six hits that don't have one yet, which adds time. ### Results | 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 profiles, from 0 to 1. | | `hits[].cluster_size`, `protein_name` | Number of proteins in the representative's cluster, and the representative's name, when available. | | `top_features_across_results[]` | Up to 20 SAE features found in the hits, ranked by mean activation: `feature_index`, `occurrence_count`, and `mean_activation`. A top feature can come from a single hit, so use `occurrence_count`, the number of hits that have it, to see which features the hits share. | | `restricted_count` | Number of hits withheld by ESM Atlas guardrails. | ## Get cluster details `esm_atlas_get_cluster_info` summarizes the cluster of a cluster representative. ### Inputs | Input | Description | | - | - | | `sequence` (required) | A cluster representative of 1 to 4,000 residues, such as a hit from [`esm_atlas_search_similar_protein_clusters`](#find-similar-protein-clusters). Other sequences return `not_found`. | ### Results | Field | Description | | - | - | | `accession`, `source`, `protein_name` | Representative's identity. | | `cluster_size` | Number of proteins in the cluster. | | `cluster_pct_characterized` | Percentage of members with a characterized Pfam domain, 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 of the representative's strongest 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, which can be empty or `null`. | ## Get SAE feature details `esm_atlas_get_sae_feature_detail` explains one of the 16,384 SAE features learned from [ESMC](/models/esmc). ### Inputs | Input | Description | | - | - | | `feature_index` (required) | A feature number from 0 to 16,383, as the other ESM Atlas tools return it. | ### Results | Field | Description | | - | - | | `feature_index` | Feature number. | | `label`, `summary`, `description` | Short label and longer interpretations. | | `category` | Broad category, such as `Catalytic function`, when available. | | `activation_pattern` | Where and how the feature tends to be active, when available. | | `exemplar_protein_families` | Example families, when available. | | `uniref90_frequency` | Number of UniRef90 sequences where the feature appears. | | `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. | ## Limits | Limit | Value | When exceeded | | - | - | - | | UniProt query | 500 characters | `invalid_input` | | UniProt entries per search | 6 | `invalid_input` | | Sequence in a UniProt result | 4,000 residues | The sequence is `null` | | Accession | 128 characters | `invalid_input` | | Sequence for protein details or cluster details | 4,000 residues | `invalid_input` | | Sequence for the similarity search | 2,048 residues | `invalid_input` | | Features computed for a sequence not in the ESM Atlas | 2,048 residues | `sequence_too_long_for_features` | | Similar proteins per search | 12 | `invalid_input` | | Stored structure read by protein details | 2 MiB | `dependency_unavailable` | | Complete result | 6 MiB | `resource_too_large` | | Tool deadline | 120 seconds | `indeterminate` | ## Errors | Code | What to do | | - | - | | `invalid_input` | Fix the input the message names, such as a FASTA header, a character that isn't an amino acid, a UniProt accession sent to the accession lookup, or a value over a limit. | | `not_found` | Check the accession or feature number. For an MGnify accession, paste the sequence instead. For cluster details, use a similarity search hit, not a UniProt sequence. | | `sequence_too_long_for_features` | Send one domain of up to 2,048 residues instead, which the ESM Atlas treats as a new sequence. The error gives `actual_length` and `max_length`. | | `restricted` | ESM Atlas [guardrails](/learn/guides/esm-atlas#guardrails) blocked the sequence. Don't try to work around it by trimming, mutating, or rephrasing. | | `rate_limited` | The ESM Atlas asked callers to slow down. Wait at least `retry_after_seconds`, then make fewer calls at once. | | `dependency_unavailable` | The ESM Atlas, UniProt, or MGnify was unavailable, too slow, or sent an unusable response. Rate limits at UniProt and MGnify also show up here. Wait and try again. | | `indeterminate` | The deadline passed, or a feature computation or similarity search ended with an unknown outcome. Don't retry automatically; wait, then ask once more. | | `resource_too_large` | The complete result is over 6 MiB. Ask for fewer results. | | `internal_error` | Try again and [tell us](https://info.biohub.org/product-feedback) if it continues. | See [Troubleshooting](/biohub-mcp/troubleshooting#error-codes) for details about codes. # Biohub MCP example prompts Source: https://docs.biohub.ai/biohub-mcp/example-prompts Try five protein research prompts and follow an ATP synthase walkthrough to start using Biohub MCP capabilities. Explore five spotlight prompts and use your AI agent to find uncharacterized protein candidates, explore molecular interactions, map mutation constraints, or interpret protein features. See the [Quickstart](/biohub-mcp/quickstart) to connect your AI agent. Interactive structures appear in clients that support the [structure viewer](/biohub-mcp/structure-viewer). > [!NOTE] > > Folding and ESMC prompts are billed to your Biohub account. Results and scores can vary between runs or when the Atlas is updated. Treat all results as hypotheses, not as established biological facts. Each spotlight video includes a 30-second edited chat replay using Biohub MCP results and structure images, with processing time compressed. ## Find uncharacterized protein candidates **Use the ESM Atlas:** Start from a protein you study and shortlist candidates using learned protein features, annotations, and structures. I want to identify new protein candidates worth investigating. Starting from Csm3 from Streptococcus thermophilus (UniProt A0A0A7HIF0), search ESM Atlas for uncharacterized relatives and show the most promising candidates. I want to identify new protein candidates worth investigating. Starting from Csm3 from Streptococcus thermophilus (UniProt A0A0A7HIF0), search ESM Atlas for uncharacterized relatives and show the most promising candidates. **What this shows:** ESM Atlas searches cluster representatives using SAE feature similarity. The agent compares candidates from clusters without characterized Pfam annotations using their lengths, shared features, and predicted structures. The 222-residue lead is close to Csm3's length; the highest-scoring hit is only 69 residues. These observations support follow-up, without establishing completeness or function. ## Explore a GLP-1 peptide and GLP-1R complex **Use ESMFold2:** Predict a defined receptor and unmodified peptide to examine their possible interaction. Model how unmodified human GLP-1(7–37) engages human GLP-1R, then show me the predicted complex. Model how unmodified human GLP-1(7–37) engages human GLP-1R, then show me the predicted complex. **What this shows:** ESMFold2 Fast predicts a complex of full-length human GLP-1R (UniProt P43220, 463 residues) and unmodified GLP-1(7–37), the 31-residue peptide from proglucagon positions 98–128 (UniProt P01275). No lipid linker, membrane, or G protein is included. Inspecting the pose and confidence estimates provides a structural hypothesis; confidence scores do not measure binding affinity or receptor activation. ## Map PETase mutation constraints **Use ESMC:** Explore which positions appear constrained or tolerant in a protein's possible mutations. Map the mutational landscape of this CaPETase sequence and show me where it is most constrained or tolerant. AADNPYQRGPDPTNASIEAATGPFAVGTQPIVGASGFGGGQIYYPTDTSQTYGAVVIVPGFISVWAQLNWLGPRLASQGFVVIGIETSVITDLPDPRGDQALAALDWATTRSPVASRIDRTRLAAAGWSMGGGGLRRAALQRPSLKAIVGMAPWNGERNWSAVTVPTLFFGGSSDAVASPNDHAKPFYNSITRAEKDYIELRNADHFFPTSANTTMAKYFISWLKRWVDNDTRYTQFLCPGPSTGLFAPVSASMNTCPF Map the mutational landscape of this CaPETase sequence and show me where it is most constrained or tolerant. AADNPYQRGPDPTNASIEAATGPFAVGTQPIVGASGFGGGQIYYPTDTSQTYGAVVIVPGFISVWAQLNWLGPRLASQGFVVIGIETSVITDLPDPRGDQALAALDWATTRSPVASRIDRTRLAAAGWSMGGGGLRRAALQRPSLKAIVGMAPWNGERNWSAVTVPTLFFGGSSDAVASPNDHAKPFYNSITRAEKDYIELRNADHFFPTSANTTMAKYFISWLKRWVDNDTRYTQFLCPGPSTGLFAPVSASMNTCPF **What this shows:** ESMC 6B scans all 259 positions in the supplied CaPETase sequence, masking each position in turn to score substitutions. The agent maps constrained and higher-entropy positions onto the structure. These scores describe model preferences, not measured enzyme activity or stability; higher entropy alone does not imply favorable substitutions. ## Interpret ATP synthase features **Use ESMC and SAEs.** Explore what the model recognizes in a familiar protein and where selected features activate on its structure. Show me what ESMC has learned about ATP synthase and map the strongest features onto its structure. Show me what ESMC has learned about ATP synthase and map the strongest features onto its structure. **What this shows:** The agent retrieves ESMC SAE feature summaries for the ATP synthase F1 alpha subunit and highlights one reported residue-region peak for each of three strong features. Their descriptions suggest nucleotide-associated and coupling patterns. Broad feature labels do not establish catalytic activity in this alpha subunit or functional roles for individual highlighted residues. > [accordion] Walk through this example in more detail > > ### What the agent does > > 1. **Identify the protein.** This example uses the 492-residue bovine mitochondrial ATP synthase F1 alpha subunit sequence from PDB 2XND, chain A. The PDB record supplies the sequence; the viewer uses a predicted structure for that sequence. > 2. **Retrieve its features.** Ask ESM Atlas for the sequence's ESMC SAE feature summaries, then retrieve descriptions of the strongest reported features. The MCP can compute a missing feature profile; an existing profile can be retrieved directly. > 3. **Map the result.** Open the Biohub structure viewer for the same sequence and highlight reported feature-region peaks, checking that sequence positions match the displayed residues. This demo marks A425, S317, and L267 for the three strongest features, using positions in the analyzed sequence. > > ### What is happening under the hood > > ESMC builds a representation of the protein from its amino acid sequence. A sparse autoencoder, or SAE, separates that representation into features that can be examined individually. Some features are associated with patterns such as structural motifs or nucleotide-binding regions. > > This workflow uses feature summaries returned by the MCP. Each highlighted residue marks a reported feature-region peak. Its location and feature description provide clues about what the model recognizes. These are starting points for investigation and should be treated as hypotheses only. > > **Displaying a structure does not necessarily mean running ESMFold2:** the agent may retrieve an existing prediction. The feature analysis and the source of the displayed structure are separate steps. > > ### Explore the result > > Compare where the features activate and ask what evidence supports their interpretations. > > For the strongest SAE feature, highlight its reported residue-region peaks. What structural regions do they occupy, and what supports the feature's interpretation? > > For the strongest SAE feature, highlight its reported residue-region peaks. What structural regions do they occupy, and what supports the feature's interpretation? > > ### Go deeper > > * [Understanding proteins with SAE features](/learn/tutorials/esmc/sae-features) explains the analysis and links to the code notebook. > * Read the [Biohub research overview](https://biohub.ai/esm/protein/about) for details about the ESM models. ## Reconstruct a protein function hypothesis **Use ESMC and the ESM Atlas:** Revisit a characterized protein as a retrospective example, treating its sequence as uncharacterized to develop a function hypothesis. Treat this protein sequence from an Icelandic hot spring metagenome as uncharacterized. Use ESMC SAE features and similar proteins in ESM Atlas to propose its most likely function. Show the strongest supporting evidence and highlight the relevant residues on its structure. MSYNKVVLVGRLTRDPETRQTLDGNLITTFTLAVNRGNNGDDVDFIRIVAFRKLAELAHNYLQKGRMVLVDGKLRINKWKTNDGQPRSTVEIWADNIVFVDSKKGDREIPDEIPYEEVFGQDVETDEDIPNDDEPPFRSHHHHHH Treat this protein sequence from an Icelandic hot spring metagenome as uncharacterized. Use ESMC SAE features and similar proteins in ESM Atlas to propose its most likely function. Show the strongest supporting evidence and highlight the relevant residues on its structure. MSYNKVVLVGRLTRDPETRQTLDGNLITTFTLAVNRGNNGDDVDFIRIVAFRKLAELAHNYLQKGRMVLVDGKLRINKWKTNDGQPRSTVEIWADNIVFVDSKKGDREIPDEIPYEEVFGQDVETDEDIPNDDEPPFRSHHHHHH **What this shows:** SSB-associated SAE features and annotated Atlas neighbors support a single-stranded DNA-binding hypothesis. The agent maps reported feature-region peaks onto a predicted structure of the exact 145-residue tagged construct. This retrospective demo reconstructs a hypothesis for a protein with [published experimental characterization](https://pubmed.ncbi.nlm.nih.gov/41870280/); the highlighted residues are model-associated peaks, not measured DNA contacts. # Biohub MCP folding tools Source: https://docs.biohub.ai/biohub-mcp/folding-tools Fold proteins and complexes with ESMFold2 through Biohub MCP. The [ESMFold2](/learn/tutorials/esmfold2) model predicts high-resolution, all-atom 3D structures of biomolecular complexes directly from sequence, with optional multiple sequence alignment (MSA) input for enhanced accuracy on challenging targets. To fold a protein or a complex, you can prompt your AI agent through the Biohub MCP, and the server will run the ESMFold2 model and returns its confidence scores for your protein. > [!NOTE] > > Folds are billed to the Biohub account you are signed in with. See [Costs](#costs). ## What you can ask Ask in your own words, and your assistant picks the tools and runs them in order. For example: Fold GFP with ESMFold2 and tell me how confident the prediction is. Fold GFP with ESMFold2 and tell me how confident the prediction is. Fold human hemoglobin's alpha and beta chains together and tell me how confident the model is in their interface. Fold human hemoglobin's alpha and beta chains together and tell me how confident the model is in their interface. Fold PETase from Ideonella sakaiensis at maximum accuracy, check the run until it finishes, and compare its scores with a standard fold. Fold PETase from Ideonella sakaiensis at maximum accuracy, check the run until it finishes, and compare its scores with a standard fold. You can use sequences instead of protein names in any of these prompts. ## Which tools your assistant uses | When you ask to | Your assistant uses | | - | - | | Fold a protein you named | [`esm_atlas_search_uniprot`](/biohub-mcp/esm-atlas-tools#search-uniprot) first, to get its sequence. Free. | | Fold a protein or a complex | [`esmfold2_fold_complex`](#fold-a-protein-or-complex), which returns scores within the call for up to 768 tokens. Larger inputs, or folds you ask to batch, become a run at one fifth of the price. | | Fold at maximum accuracy | [`esmfold2_fold_max_accuracy`](#fold-at-maximum-accuracy), which starts a run that finishes in minutes to hours. | | Check on a fold that is still running | [`biohub_get_inference_run`](#check-a-run), which returns the run's status, and its scores once it is done. Free. | | See the structure in 3D | [`ui_show_structure`](/biohub-mcp/structure-viewer), which opens an interactive viewer. One protein is free; a complex of up to 768 tokens is a billed fold. | | Look up scores for a protein already in the ESM Atlas | [`esm_atlas_get_protein_details`](/biohub-mcp/esm-atlas-tools#get-protein-details), which returns its stored pTM and mean pLDDT. Free. | ## How a fold runs **1. Your assistant gets the sequences** When you name a protein or give a UniProt accession, your assistant first looks up its sequence with the free `esm_atlas_search_uniprot` tool. You can also use the protein sequence directly. A ligand can given by its name or as a SMILES string, as [described below](#entities). **2. Small folds finish within the call** For up to 768 tokens, `esmfold2_fold_complex` folds right away and returns `done` with the scores and the exact cost. **3. Larger folds become a run** Inputs over 768 tokens, folds you ask to batch, and every maximum-accuracy fold return `queued` with a `run_id`. **4. Your assistant checks the run** `biohub_get_inference_run` reads the run and waits up to 5 seconds for it to finish. Your assistant calls it again until the run is `done`. The confidence scores appear in the result once the run is `done`. Small folds return the [confidence scores](#read-the-scores) in step 2, as soon as the call finishes. Larger folds return them in step 4, when `biohub_get_inference_run` reports the run as `done`. Biohub keeps a run's result for 31 days. A run that hasn't started within 24 hours is cancelled and not charged. > [!TIP] > > A name can match several proteins. > "PETase" alone can return other PET-degrading enzymes first, so add the organism, as in "PETase from *Ideonella sakaiensis*", or give the UniProt accession. > Your assistant can tell you which entry it folded. > [!WARNING] > > Every fold call starts new work and is billed again, even for the same input. > If a call returns `indeterminate`, the fold may have run and been billed, so don't retry it automatically. ## Read the scores All scores run from 0 to 1, and higher means the model is more confident. | Score | What it measures | Returned for | | - | - | - | | pTM | The overall fold. | Every fold | | pLDDT | The local structure at each residue, nucleotide, or ligand atom. Results give the mean, minimum, and maximum. | Every fold, and per chain for protein-only folds when available | | Interface pTM | How all the chains of a complex sit against each other. | Complexes | | ipTM | How one pair of chains sits together. | Complexes, when Biohub returns it | A high pTM with a low interface pTM means each part is confident on its own, but the contact between them is not. These scores are the model's confidence, not measured binding or experimental validation. ## Get the full outputs The folding tools return summary scores, so the results stay small enough for your assistant to read. They don't return the large arrays a fold can produce: atom coordinates, per-residue pLDDT, the PAE matrix, the distogram, or embeddings. To get those, call the Biohub Platform API with an API key: | You need | Use | | - | - | | Full outputs of a new fold of up to 768 tokens | [fold](/api/protein/models/fold) for proteins, or [fold\_all\_atom](/api/protein/models/fold_all_atom) for DNA, RNA, or ligands | | Full outputs of a larger fold, or at the batch price | [Batch folding](/api/protein/models/batch_folding) | | Full outputs at maximum accuracy | [fold\_max\_accuracy](/api/protein/models/fold_max_accuracy) | | The result of a run you started here | The Batch API's [Status](/api/protein/models/batch_status) endpoint, with the `run_id` as its `task_id` | * A result includes coordinates and per-residue pLDDT. PAE and embeddings are included only when the request asks for them, with options such as `include_pae` and `include_embeddings`, and the folding tools don't ask for them. * Coordinate and embedding arrays can be large. [Response formats](/api/protein/models/response-formats) explains how to receive them in a smaller binary format and compress the response. ## Costs Costs are measured in Biohub credits and grow with the square of the input size. | Tokens | Fold within the call | Batch run | Maximum accuracy | | - | - | - | - | | 56, such as GB1 | 0.016 | 0.003 | 0.28 | | 300 | 0.45 | 0.09 | 1.6 | | 768 | 2.95 | 0.59 | 4.4 | | 2,000 | Batch only | 4 | 14 | | 4,096 | Batch only | 16.8 | 37 | * A batch run is what you get with `use_batch_api`, and for any input over 768 tokens. * A fold within the call returns what Biohub billed. A run returns its price when it is queued, and the run's `usage` shows what Biohub billed. * When an input has a ligand, a queued run's price can be an upper bound, because Biohub may count the ligand as fewer tokens. * Maximum accuracy has no batch discount, and by default your account can start 10 maximum-accuracy runs a day. A run that fails isn't charged, but it still counts toward the 10. ### Tokens A token is one residue or nucleotide, or one heavy atom (any atom except hydrogen) of a ligand, and every chain counts. For example, a 300-residue homodimer with one ATP is 300 × 2 + 31 = 631 tokens, because ATP has 31 heavy atoms. ## Fold a protein or complex `esmfold2_fold_complex` folds one protein, several protein chains, or proteins with DNA, RNA, or ligands. Examples are an antibody's heavy and light chains, a homodimer, a binder and its target, or a protein bound to ATP. ### Inputs | Input | Description | | - | - | | `entities` (required) | 1 to 16 molecules, up to 4,096 tokens in total, as [described below](#entities). | | `model_id` | `esmfold2-fast-2026-05`, the default, is the smaller model built for speed. `esmfold2-2026-05` is the larger flagship model. | | `use_batch_api` | `true` queues a run at one fifth of the price instead of folding within the call. Defaults to `false`. | ### entities Each entry in `entities` is one chain, named `A`, `B`, `C`, and so on in the order you list them. The tool takes sequences, so when you name a protein, your assistant fills in its sequence. | Field | Description | | - | - | | `type` (required) | `protein`, `dna`, `rna`, or `ligand`. Always required, because A, C, G, and T are also amino-acid letters. | | `sequence` | For a protein, DNA, or RNA chain: its one-letter codes. Whitespace is removed and letters are made uppercase. | | `ccd` | For a ligand: a [PDB Chemical Component Dictionary](https://www.wwpdb.org/data/ccd) code, such as `ATP`. | | `smiles` | For a ligand: a SMILES string of up to 2,000 characters, such as `CC(=O)OC1=CC=CC=C1C(=O)O` for aspirin. | * Give a ligand either `ccd` or `smiles`, not both. * Give each chain as its own entry: `|` and `:` inside a sequence are refused, and there is no `copies` field. For a homodimer, list the protein twice. * A protein sequence that looks like DNA or RNA still folds as a protein, with a warning. This example folds a homodimer with one ATP: ```json theme={null} { "entities": [ { "type": "protein", "sequence": "MKTAYIAKQRQISFVKSHFSRQ" }, { "type": "protein", "sequence": "MKTAYIAKQRQISFVKSHFSRQ" }, { "type": "ligand", "ccd": "ATP" } ] } ``` ### Results `esmfold2_fold_complex` and `esmfold2_fold_max_accuracy` return the same fields. | Field | Description | | - | - | | `execution_status` | `done` when the fold finished within the call, or `queued` when it started a run. | | `run_id` | Only when `queued`. Pass it to [`biohub_get_inference_run`](#check-a-run). | | `model_id` | The model the fold asked for. | | `chains` | Each chain's `id`, `type`, and `length` in residues, nucleotides, or ligand heavy atoms. | | `cost` | `credits`, and a `basis` of `exact`, or `upper_bound` when a ligand may count as fewer tokens. | | `summary` | Only when `done`. The [scores](#read-the-scores), as described below. | | `warnings` | Up to eight notes, such as a score that Biohub didn't return. | | `summary` field | Description | | - | - | | `ptm` | pTM. | | `plddt_summary` | `mean`, `minimum`, and `maximum` pLDDT over every residue, nucleotide, and ligand atom. | | `chains[].mean_plddt` | Each chain's mean pLDDT, for protein-only folds when available. | | `interface_ptm` | Interface pTM, for a complex. | | `pair_chains_iptm[]` | `chain_a`, `chain_b`, and `iptm` for each pair of chains, when Biohub returns it. | This is a fold of GB1 on the Biohub Platform: ```json theme={null} { "execution_status": "done", "model_id": "esmfold2-fast-2026-05", "chains": [{ "id": "A", "type": "protein", "length": 56 }], "cost": { "credits": 0.0157, "basis": "exact" }, "summary": { "chains": [{ "id": "A", "type": "protein", "length": 56, "mean_plddt": 0.833 }], "ptm": 0.748, "plddt_summary": { "mean": 0.833, "minimum": 0.728, "maximum": 0.891 } }, "warnings": [] } ``` ## Fold at maximum accuracy `esmfold2_fold_max_accuracy` takes the same `entities` as `esmfold2_fold_complex`, and nothing else. * Biohub builds an alignment from UniRef30 and ColabFold; the tool can't take your own. * It folds five times with different seeds using `esmfold2-2026-05-cutoff-2025`, needs at least four to succeed, and keeps the most confident: the highest ipTM for a complex, or the highest mean pLDDT for one chain. * It always returns `queued`, and a run takes minutes to hours. * Its results have the same fields as `esmfold2_fold_complex`, without per-chain pLDDT. * It is billed when the run finishes, as [Costs](#costs) shows. ## Check a run `biohub_get_inference_run` reads one run by its `run_id`. It is read-only, starts no compute, and costs nothing. ### Inputs | Input | Description | | - | - | | `run_id` (required) | The `run_id` a fold tool returned. | | `wait_seconds` | How long to wait for the run to finish, from 0 to 5 seconds. Defaults to `5`; `0` reads once. | ### Results | Field | Description | | - | - | | `run_id` | The run that was read. | | `execution_status` | `queued`, `in_progress`, `done`, `failed`, or `cancelled`. | | `results_expire_at` | When Biohub deletes the result, as a UTC time such as `2026-12-05T17:33:11.299Z`. | | `error_message` | Biohub's reason, for a failed or cancelled run. | | `model_id` | The model that ran. | | `usage` | The `credits` Biohub billed for the fold. Reading the run is free. | | `summary` | Once `done`, the same [scores](#read-the-scores) as a fold within the call. | | `warnings` | Up to eight notes. | * A run that is still `queued` or `in_progress` is normal; ask again later. * You can read any fold run on your account, including folds you submitted through the [Batch API](/api/protein/models/batch_folding). Another user's run reads as `not_found`. * A failed or cancelled run doesn't restart; folding again starts a new run and bills again. * If a finished run's result can't be read in time, the answer keeps its status and `usage`, adds a warning, and leaves out `summary`. Read the run again later. ## Limits | Limit | Value | When exceeded | | - | - | - | | Molecules per fold | 16 | `invalid_input` | | Fold size | 4,096 tokens | `sequence_too_long_to_fold` | | Fold within the call | 768 tokens | The fold runs as a batch instead | | SMILES length | 2,000 characters | `invalid_input` | | Maximum-accuracy runs | 10 a day per account, by default | `rate_limited` | | Run result retention | 31 days | `expired` | | Time for a run to start | 24 hours | The run is cancelled and not charged | Biohub and its fold workers can count a ligand's tokens differently. If that would put a fold over a worker's limit, the tool refuses the fold before submitting anything, and the error says what to change. ## Errors | Code | What to do | | - | - | | `invalid_input` | Fix the molecule, type, or sequence the message names. Nothing was sent to Biohub. | | `sequence_too_long_to_fold` | Shorten the input by the amount the message gives. Nothing was submitted. | | `rate_limited` | Your account reached a Biohub limit or ran out of credits. Wait at least `retry_after_seconds` when it is given. | | `restricted` | Biohub refused the request for your account, for example because it can't use the model. Don't try to work around it. | | `not_found` | The `run_id` isn't one of your account's runs. | | `expired` | The run is past its 31 days. Fold again if you still need it. | | `indeterminate` | The fold may have run and been billed. Don't retry automatically; if the error has a `run_id`, check that run first. | | `dependency_unavailable` | Biohub is temporarily unavailable. Wait and try again, or set `use_batch_api` to `true` when the message recommends it. | | `internal_error` | Try once more later, and [tell us](https://info.biohub.org/product-feedback) if it continues. | When an error includes `credits` or `billed_calls`, they describe the work Biohub confirmed before the failure. See [Troubleshooting](/biohub-mcp/troubleshooting#error-codes) for the codes every tool shares. # Biohub MCP mutation scoring tools Source: https://docs.biohub.ai/biohub-mcp/mutation-scoring-tools Score named amino-acid substitutions or scan a protein for mutation tolerance with ESMC through Biohub MCP. The [ESMC](/learn/tutorials/esmc) model learns protein structure and function from sequence, so it can estimate how likely each amino acid is at every position and predict which mutations a protein is likely to tolerate. To find out how a protein responds to mutations or amino-acid substitutions, prompt your AI agent, and the Biohub MCP scores them with ESMC to return predicted scores. > [!NOTE] > > Calls are billed to the Biohub account you are signed in with. ## What you can ask Ask in your own words, and your AI agent picks the tool for your task. For example: Use ESMC to score the S65T and Y66H substitutions in GFP and explain what the scores mean. Use ESMC to score the S65T and Y66H substitutions in GFP and explain what the scores mean. Scan PETase from Ideonella sakaiensis for mutation tolerance with ESMC and list the most constrained and most tolerant positions. Scan PETase from Ideonella sakaiensis for mutation tolerance with ESMC and list the most constrained and most tolerant positions. You can paste a sequence instead of a name in either prompt. > [!TIP] > > Positions count from 1 along the sequence that is scored. > When you name a protein, that is its UniProt sequence, which can number residues differently from a paper, for example when the paper leaves out a signal peptide. > If the numbering doesn't match, `expected_wild_type` makes the call fail instead of scoring the wrong residue. ## Which tools your AI agent uses | When you ask to | Your assistant uses | | - | - | | Score a protein you named | [`esm_atlas_search_uniprot`](/biohub-mcp/esm-atlas-tools#search-uniprot) first, to get its sequence. Free. | | Score substitutions you already have, such as S65T or a list from a paper | [`esmc_score_mutations`](#score-named-substitutions), which scores each one. For a 300-residue protein, each position costs 0.03 credits, and one call covers up to 8 positions. | | Find where a protein tolerates change, before you have picked substitutions | [`esmc_scan_mutation_tolerance`](#scan-mutation-tolerance), which ranks the positions. For a 300-residue protein, scanning every position costs 9 credits. | ## How scoring works ESMC hides the residue at one position and predicts how likely each amino acid is there. A substitution's score is ln P(new residue) - ln P(original residue) at that hidden position: * A positive score means ESMC finds the new residue more likely than the original. * A negative score means ESMC prefers the original. * Each substitution is scored on its own on the original sequence, not combined with the others. A scan scores all 20 amino acids at every position it covers, then ranks the positions by how constrained they are: * `entropy_bits`, the default, measures how spread out ESMC's prediction is at the position. Low entropy means few residues fit, so the position is constrained. * `negative_substitution_fraction` is the share of the 19 other amino acids that score below the original. A high fraction means the position is constrained. These scores are predictions, not measured fitness, stability, or activity. To run the same scoring using, see the [mutation scoring tutorial](/learn/tutorials/esmc/mutation-scoring). ## Costs Each position costs the protein's length divided by 10,000 credits, whichever ESMC model you choose. | | 56 residues, such as GB1 | 300 residues | 1,000 residues | | - | - | - | - | | Score substitutions at 1 position | 0.0056 | 0.03 | 0.1 | | Score substitutions at 8 positions, the most per call | 0.045 | 0.24 | 0.8 | | Largest scan | 0.31 for all 56 positions | 9 for all 300 positions | 20 for 200 positions | Scoring several substitutions at the same position costs the same as scoring one. A scan never costs more than 20 credits. > [!WARNING] > > Every call starts new work and bills again, even for the same input. > If a call returns `indeterminate`, it may have been billed already, so don't retry it automatically. ## Score substitutions `esmc_score_mutations` takes your protein sequence and any desired amino-acid substitutes and returns a score for each substitution. ### Inputs | Input | Description | | - | - | | `sequence` (required) | One protein chain of 1 to 2,046 residues in one-letter codes. Whitespace is removed, and `\|` and `:` are refused. | | `mutations` (required) | 1 to 64 substitutions at up to 8 different positions, as described below. | | `model_id` | `esmc-300m-2024-12`, `esmc-600m-2024-12`, or `esmc-6b-2024-12`, with about 300 million, 600 million, and 6 billion parameters. Defaults to `esmc-600m-2024-12`. | Each entry in `mutations` names one substitution: | Field | Description | | - | - | | `position` | Position in the sequence, counting from 1. | | `expected_wild_type` | The residue you expect at that position. If the sequence has a different one, the call fails, which catches numbering mistakes. | | `alternate` | The new residue. | Residues are one of the 20 standard amino acids, as uppercase one-letter codes. This example scores W43F and W43A in GB1: ```json theme={null} { "sequence": "MTYKLILNGKTLKGETTTEAVDAATAEKVFKQYANDNGVDGEWTYDDATKTFTVTE", "mutations": [ { "position": 43, "expected_wild_type": "W", "alternate": "F" }, { "position": 43, "expected_wild_type": "W", "alternate": "A" } ] } ``` ### Results | Field | Description | | - | - | | `scores` | One row per substitution, in the order you gave them: `position`, `expected_wild_type`, `alternate`, `score`, and `wild_type_log_probability`. | | `usage` | `logits_calls`, the ESMC calls made, and the `credits` Biohub billed. | | `model_id` | The ESMC model that scored. | Both substitutions in the example share one position, so they took one ESMC call: ```json theme={null} { "model_id": "esmc-600m-2024-12", "scores": [ { "position": 43, "expected_wild_type": "W", "alternate": "F", "score": 0.25, "wild_type_log_probability": -3.1464 }, { "position": 43, "expected_wild_type": "W", "alternate": "A", "score": 0.75, "wild_type_log_probability": -3.1464 } ], "usage": { "credits": 0.0056, "logits_calls": 1 } } ``` ## Scan mutation tolerance `esmc_scan_mutation_tolerance` finds the positions where a protein is most and least tolerant to change. It returns the top positions of each kind with their strongest substitutions, not the full matrix of scores. ### Inputs | Input | Description | | - | - | | `sequence` (required) | One protein chain of 1 to 2,046 residues, as for `esmc_score_mutations`. | | `positions` | `"all"`, the default, a list of positions such as `[12, 43, 51]`, or a window such as `{ "start": 10, "end": 40 }` that includes both ends. | | `model_id` | `esmc-300m-2024-12`, `esmc-600m-2024-12`, or `esmc-6b-2024-12`. Unlike scoring, the scan defaults to the largest model, `esmc-6b-2024-12`. | | `ranking_metric` | `entropy_bits`, the default, or `negative_substitution_fraction`, as [How scoring works](#how-scoring-works) describes. | One scan covers at most 400 positions, and at most 200,000 divided by the protein's length. For a longer request, the tool returns `invalid_input` with a window that fits; it never shortens the scan for you. ### Results | Field | Description | | - | - | | `execution_status` | `done`, or `partial` when the time limit or a rate limit stopped the scan early. | | `most_constrained` | Up to 10 positions, most constrained first. | | `most_tolerant` | Up to 10 positions, most tolerant first. When fewer than 20 positions are scanned, the two lists can share positions. | | `coverage` | How many positions were `requested` and `scanned`, the `skipped` positions whose residue isn't one of the 20 standard amino acids, and the `unscanned` positions a partial scan didn't reach. | | `usage` | `logits_calls` and the `credits` Biohub billed, for finished positions only. | | `model_id` | The ESMC model that scanned. | | `warnings` | Why positions were skipped or the scan stopped early. | Each position in `most_constrained` and `most_tolerant` has: | Field | Description | | - | - | | `position` | Position in the sequence, counting from 1. | | `wild_type` | The residue the sequence has there. | | `entropy_bits` | Entropy of ESMC's prediction at the position. Low means constrained. | | `negative_substitution_fraction` | Share of the 19 other amino acids that score below the original. High means constrained. | | `top_substitutions` | The three highest-scoring substitutions, each with its `alternate` and `score`. | For example, a full scan of GB1 with the default model ranked Asp46 as most constrained, with every substitution scoring below the original, and Gly38 as most tolerant. It made 56 ESMC calls for 0.31 credits. ### Partial scans A scan that reaches the time limit, or a rate limit after some positions finished, returns `partial` and bills only the finished positions. To finish it, scan again with `coverage.unscanned` as `positions`. Each scan ranks only the positions it covers, so compare the two results to get the full picture. ## Limits | Limit | Value | When exceeded | | - | - | - | | Protein length | 1 to 2,046 residues | `invalid_input` | | Substitutions per call | 64, at up to 8 positions | `invalid_input` | | Positions per scan | 400, and at most 200,000 divided by the length | `invalid_input`, with a window that fits | | Cost of one scan | 20 credits | Can't be exceeded, because of the position limit | ## Errors | Code | What to do | | - | - | | `invalid_input` | Fix the sequence, positions, or substitutions the message names. A wrong `expected_wild_type` usually means the numbering is off by one. Nothing was billed. | | `rate_limited` | Your account reached a Biohub limit or ran out of credits. Wait at least `retry_after_seconds` when it is given. | | `restricted` | Biohub refused the request for your account. Don't try to work around it. | | `indeterminate` | The call may have been billed. Don't retry automatically. | | `dependency_unavailable` | Biohub is temporarily unavailable. Wait and try again. | | `internal_error` | Try once more later, and [tell us](https://info.biohub.org/product-feedback) if it continues. | When an error includes `credits` or `billed_calls`, it describes the work Biohub confirmed before the failure. A later failure doesn't refund earlier ESMC calls in the same request. See [Troubleshooting](/biohub-mcp/troubleshooting#error-codes) for details about codes. # Biohub MCP server Source: https://docs.biohub.ai/biohub-mcp/overview Connect your AI assistant to Biohub MCP to search the ESM Atlas, explain protein SAE features, and more. The Biohub MCP connects your AI assistant to the [ESM Atlas](/learn/guides/esm-atlas) and to the [ESMFold2](/models/esmfold2) and [ESMC](/models/esmc) models on the Biohub Platform through the [Model Context Protocol](https://modelcontextprotocol.io/) server. You ask your AI assistant a question, and the assistant decides which MCP tools (a callable function) to call and passes results from one tool to the next. Its [ESM Atlas tools](/biohub-mcp/esm-atlas-tools) give your assistant the same abilities as the [ESM Atlas Agent](https://biohub.ai/esm/protein/atlas), the "Ask the atlas" box on the ESM Atlas site. ```mermaid theme={null} flowchart LR You([You]) --> Client[AI client] Client -->|Tool call| MCP[Biohub MCP] MCP --> Atlas[ESM Atlas] MCP --> DBs[UniProt, EMBL-EBI MGnify] MCP --> BHP[Biohub Platform: ESMFold2 and ESMC] MCP -->|Result and viewer| Client ``` ## What the MCP server can do * Turn a protein name or a UniProt, UniParc, or MGnify accession into an amino-acid sequence. * Find ESM Atlas cluster representatives whose SAE feature profiles are closest to your protein, optionally only clusters with no characterized Pfam domains. * View a stored or newly predicted structure, colored by chain or by confidence, with the residues you care about highlighted. * Fold and view a complex of proteins, DNA, RNA, and small molecules; see [Complexes](/biohub-mcp/structure-viewer#complexes). * Fold proteins and complexes of up to 4,096 tokens with ESMFold2 and get confidence scores, including at maximum accuracy; see [Folding tools](/biohub-mcp/folding-tools). ## Get started > [card] [Quickstart](/biohub-mcp/quickstart) > > Add the server to your client and run a first request in a few minutes. > [card] [Example prompts](/biohub-mcp/example-prompts) > > Prompts to copy, with the tools they use and what to expect back. > [card] [Skills](/biohub-mcp/skills/overview) > > Step-by-step instructions your client follows, such as reconstructing microscopy data with WaveOrder. > [card] [ESM Atlas tools](/biohub-mcp/esm-atlas-tools) > > Look up a protein, its SAE features, and similar proteins in the ESM Atlas, and read the results. > [card] [Structure viewer](/biohub-mcp/structure-viewer) > > Show a structure in an interactive Mol\* viewer, then export it. Connect to the MCP by signing in your browser with a free Biohub account. Atlas tools are free, and folds and ESMC scoring are billed to that account. A tool is a named action the Biohub MCP can carry out. Folding and ESMC tools start billed work on the Biohub Platform; only queued folds create a run you can read later. Your client may add a prefix to tool names, such as `mcp__biohub__esm_atlas_search_uniprot`. The viewer can fold a billed complex, so it is marked compute and non-idempotent, like the folding and ESMC tools. See [Why some calls take longer](/biohub-mcp/troubleshooting#why-some-calls-take-longer) for what clients may ask you to approve. ### ESM Atlas tools Atlas tools are free to use, and can look up information and compute results without creating saved items or IDs. See [ESM Atlas tools](/biohub-mcp/esm-atlas-tools) for inputs, results, and errors. | Tool | What it does | | - | - | | `esm_atlas_search_uniprot` | Searches UniProt by name, accession, or fielded query and returns sequences. | | `esm_atlas_lookup_accession` | Resolves a UniParc or MGnify accession to a sequence. | | `esm_atlas_get_protein_details` | Returns a protein's ESM Atlas record and up to ten of its strongest SAE features. | | `esm_atlas_search_similar_protein_clusters` | Finds ESM Atlas cluster representatives with similar SAE feature profiles. | | `esm_atlas_get_cluster_info` | Summarizes a cluster's size, characterization, Pfam domains, taxonomy, and features. | | `esm_atlas_get_sae_feature_detail` | Explains one of the 16,384 SAE features. | ### Structure viewer See [Structure viewer](/biohub-mcp/structure-viewer) for view options and export. | Tool | What it does | | - | - | | `ui_show_structure` | Shows a protein's stored or predicted structure in an interactive Mol\* viewer where supported, with an optional PNG preview. It also folds and shows complexes of proteins, DNA, RNA, and ligands, billed to your account. The viewer is an MCP App that visualizes 3D structures. | ### Folding tools See [Folding tools](/biohub-mcp/folding-tools) for how a fold runs and how to read the scores. | Tool | What it does | | - | - | | `esmfold2_fold_complex` | Folds a protein or complex with ESMFold2 and returns confidence scores, within the call or as a run. | | `esmfold2_fold_max_accuracy` | Folds at maximum accuracy with an alignment Biohub builds, as a run. | | `biohub_get_inference_run` | Reads a fold run's status and, once it is done, its scores. Free. | ### Mutation scoring tools See [Mutation scoring tools](/biohub-mcp/mutation-scoring-tools) for inputs, results, and costs. | Tool | What it does | | - | - | | `esmc_score_mutations` | Scores named substitutions with ESMC. | | `esmc_scan_mutation_tolerance` | Finds a protein's most constrained and most tolerant positions with ESMC. | ### Resource tools See [MCP resource reference](/biohub-mcp/resource-tools) for inputs, limits, and errors. | Tool | What it does | | - | - | | `list_resources` | Lists the Skills and other resources, for clients that cannot list MCP resources directly. | | `read_resource` | Reads one Skill file by its `skill://` URI, for clients that cannot read MCP resources directly. | ## MCP server vs. REST APIs You can complete similar tasks using the Biohub MCP server or the ESM Atlas and Biohub Platform APIs, but the inputs and outputs differ. For example, the MCP tools take raw sequences, while several REST endpoints take a protein hash, and the folding tools return scores but not the structure files the API returns. Choose the Biohub MCP when you are working with an AI client and you want the assistant to choose the best tool. Use the APIs when you are writing code or creating workflows that need fixed requests, direct access to responses, or greater control over your results. The Biohub Platform APIs need an API key; the MCP tools use your sign-in instead. | MCP tool | Closest REST endpoint | | - | - | | `esm_atlas_search_uniprot` | [Resolve a UniProt ID](/api/protein/atlas/proteins/uniprot) | | `esm_atlas_lookup_accession` | None | | `esm_atlas_get_protein_details` | [Get protein](/api/protein/atlas/proteins/get) | | `esm_atlas_search_similar_protein_clusters` | [Similarity search](/api/protein/atlas/similarity-search) | | `esm_atlas_get_cluster_info` | [Get cluster](/api/protein/atlas/clusters) | | `esm_atlas_get_sae_feature_detail` | [Get SAE feature](/api/protein/atlas/features/detail) | | `ui_show_structure` | [Get protein](/api/protein/atlas/proteins/get) for a stored structure, [Fold](/api/protein/models/fold) to predict one, or [fold\_all\_atom](/api/protein/models/fold_all_atom) for a complex | | `esmfold2_fold_complex` | [Fold](/api/protein/models/fold) or [fold\_all\_atom](/api/protein/models/fold_all_atom) within the call, or [Batch folding](/api/protein/models/batch_folding) for a run | | `esmfold2_fold_max_accuracy` | [fold\_max\_accuracy](/api/protein/models/fold_max_accuracy) | | `biohub_get_inference_run` | [Batch API](/api/protein/models/batch_overview#track-progress) status and results | | `esmc_score_mutations`, `esmc_scan_mutation_tolerance` | [Logits](/api/protein/models/logits) | ## Next steps * Set up the MCP using the [Quickstart](/biohub-mcp/quickstart). # Connect to the Biohub MCP and run your first query Source: https://docs.biohub.ai/biohub-mcp/quickstart Add the Biohub MCP server to Claude, Codex, ChatGPT, Cursor, VS Code, or another MCP client, sign in with a free Biohub account, and view your first protein structure. ## Before you begin You need: * A free Biohub account with a verified email address. Any email address works once you verify it. If you don't have an account yet, [create a free account](https://biohub.ai/sign-up). * An MCP client that supports OAuth sign-in, such as Claude Code, Codex, Claude.ai or Claude Desktop, ChatGPT, Cursor, or VS Code. You don't need an API key. > [!TIP] > > Some [Skills](/biohub-mcp/skills/overview), such as the WaveOrder Skills, run commands on your computer, so they need a client that can, such as Claude Code, Codex, or Cursor. **1. Add Biohub MCP to your client** > [tab] Claude Code > > Run `claude --version` to check that you have Claude Code 2.1.81 or later. > > ```bash theme={null} > claude mcp add --transport http biohub https://biohub.ai/mcp > ``` > > Add `--scope user` to make it available in every project. > Start a new `claude` session, enter `/mcp`, select `biohub`, and choose to sign in. > To check the connection later, enter `/mcp` or run `claude mcp get biohub`. > [tab] Codex > > Run `codex --version` to check that you have Codex 0.148.0 or later. > Older versions also connect, with a different sign-in method that Biohub MCP accepts. > > ```bash theme={null} > codex mcp add biohub --url https://biohub.ai/mcp > ``` > > Codex opens the sign-in page in your browser right away. > If it doesn't, run `codex mcp login biohub`. > Start a new `codex` session to use it. > Run `codex mcp list`, or enter `/mcp` in a Codex session, to check that `biohub` is connected. > > The command writes this entry to `~/.codex/config.toml`, which you can also add by hand: > > ```toml theme={null} > [mcp_servers.biohub] > url = "https://biohub.ai/mcp" > ``` > > If you add it by hand, run `codex mcp login biohub` to sign in. > > The ChatGPT desktop app and the Codex IDE extension share this configuration, so `biohub` appears there too. > To add it from the ChatGPT desktop app instead, open **Settings**, then **MCP servers**, select **Add server**, enter `biohub` as the name, select **Streamable HTTP**, enter `https://biohub.ai/mcp`, save, and select **Restart**. > Type `/mcp` in the composer to see the connected servers. > This is separate from the developer-mode apps you add in ChatGPT on the web. > See the [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp) for more options. > [tab] Claude > > These steps work in Claude.ai and Claude Desktop, which share your account's connectors, so adding Biohub once covers both. > > 1. Open **Customize**, then **Connectors**. > 2. Click **+**, then **Add custom connector**. > 3. Enter `Biohub` as the name and `https://biohub.ai/mcp` as the remote MCP server URL. > 4. If Claude asks which OAuth client to use, choose **Use Claude's published identity**, and leave any client ID and secret fields empty. > 5. Click **Add**, then **Connect**. > 6. In a chat, click **+**, select **Connectors**, and turn on Biohub. > > On Team and Enterprise plans, only an Owner can add a custom connector, under **Organization settings**, then **Connectors**, choosing **Use Claude's published identity**. > Members then click **Connect** under **Customize**, then **Connectors**, and each signs in with their own Biohub account. > Free plans allow one custom connector. > [tab] ChatGPT > > Developer mode is available on the web for Plus, Pro, Business, Enterprise, and Education accounts. > On a workspace plan, an admin may need to allow it. > > 1. In ChatGPT on the web, open **Settings**, then **Security and login**, and turn on **Developer mode**. > 2. Open [chatgpt.com/plugins](https://chatgpt.com/plugins) and click **+** to create a developer-mode app for a remote MCP server. > 3. Enter `Biohub` as the name and `https://biohub.ai/mcp` as the MCP server URL, select **OAuth**, leave any client ID and secret fields empty, and create it. > 4. In a chat, select **Developer mode** from the **+** menu and select Biohub. > > For the ChatGPT desktop app, use the **Codex** tab. > [tab] Cursor > > Add this entry to `~/.cursor/mcp.json` for all projects, or to `.cursor/mcp.json` in one project, keeping any servers already listed there. > You can also add the URL in **Cursor Settings**, then **MCP**. > > ```json theme={null} > { > "mcpServers": { > "biohub": { > "url": "https://biohub.ai/mcp" > } > } > } > ``` > > In **Cursor Settings**, then **MCP**, click **Login** or **Connect** next to `biohub`. > When it's connected, its tools are listed there; restart Cursor if it doesn't pick up the change. > [tab] VS Code > > VS Code uses MCP servers in Copilot Chat. > If your organization manages GitHub Copilot, its policy must allow MCP servers. > > Run **MCP: Add Server** from the Command Palette and follow the prompts, or add this entry to `.vscode/mcp.json` in your workspace, keeping any servers already listed there: > > ```json theme={null} > { > "servers": { > "biohub": { > "type": "http", > "url": "https://biohub.ai/mcp" > } > } > } > ``` > > To add it for your user profile instead, run **MCP: Open User Configuration** and add the same entry. > Start the `biohub` server from the MCP view or the configuration file, and sign in when asked. > Run **MCP: List Servers** to see its status, and select **Configure Tools** in Chat to turn the Biohub tools on or off. > [tab] Other > > Any MCP client that supports Streamable HTTP and OAuth sign-in can connect, such as Antigravity CLI. > > 1. Enter `https://biohub.ai/mcp` as the server URL, and choose Streamable HTTP, sometimes labeled HTTP, if the client asks. > 2. Choose OAuth sign-in if the client asks, and leave any client ID and secret fields empty. > 3. Don't select the older SSE transport, which can't connect. **2. Sign in in your browser** Your client opens the Biohub sign-in page in your browser. Check that the address is a Biohub address, as [Security and privacy](/biohub-mcp/security#sign-in-only-on-the-biohub-sign-in-page) explains, then sign in with your Biohub account. Your client keeps the sign-in and renews it for you, so you never copy a token or a key. **3. Run a first request** Show me the 3D structure of green fluorescent protein (GFP), colored by confidence, with its chromophore residues Ser65, Tyr66, and Gly67 highlighted. Look at the structure and tell me where the chromophore sits and how confident the prediction is. Show me the 3D structure of green fluorescent protein (GFP), colored by confidence, with its chromophore residues Ser65, Tyr66, and Gly67 highlighted. Look at the structure and tell me where the chromophore sits and how confident the prediction is. Copy and paste the prompt above into your AI client. Your assistant finds GFP from *Aequorea victoria* in UniProt ([P42212](https://www.uniprot.org/uniprotkb/P42212), 238 residues) with `esm_atlas_search_uniprot`, then shows its structure with `ui_show_structure`. If the ESM Atlas has no stored structure for GFP, it predicts one for your request, which takes a little longer. You should see an 11-stranded beta barrel with a helix running through its center, which carries the three highlighted chromophore residues. The prediction's pTM is about 0.91, and most residues are colored dark blue for high confidence. Clients that support MCP Apps show the structure in an interactive viewer you can rotate, and other clients show an image of it. This request is free. Folding, mutation scoring, and complexes are billed to your account, as the [Folding tools](/biohub-mcp/folding-tools#costs) and [Mutation scoring tools](/biohub-mcp/mutation-scoring-tools#costs) pages show. If your assistant doesn't find the Biohub tools, or your client still says you need to sign in, see [Troubleshooting](/biohub-mcp/troubleshooting#no-tools-show-up). ## Connection details The table below lists the settings your AI client uses to reach the Biohub MCP server. | Setting | Value | | :- | :- | | Server URL | `https://biohub.ai/mcp` | | Transport | Streamable HTTP | | Authentication | Sign-in in your browser with a free Biohub account. No API key. | | Suggested server name | `biohub` | Any verified email address can sign in, and you can [create a free account](https://biohub.ai/sign-up) if you don't have one. Your client opens the sign-in page for you the first time it connects. > [!NOTE] > > Opening the URL in a browser shows `405 Method Not Allowed`. That is expected, because MCP clients send POST requests to it. ## Next steps * Try more [Example prompts](/biohub-mcp/example-prompts), such as finding proteins similar to GFP, folding a protein, or scoring mutations. * Learn what the tools accept and return in the [ESM Atlas tools](/biohub-mcp/esm-atlas-tools), [Folding tools](/biohub-mcp/folding-tools), and [Mutation scoring tools](/biohub-mcp/mutation-scoring-tools) references. * Follow a [Skill](/biohub-mcp/skills/overview), such as the [WaveOrder reconstruction tutorial](/biohub-mcp/skills/waveorder-tutorial), which needs a client that can run commands on your computer. # Biohub MCP resource tools reference Source: https://docs.biohub.ai/biohub-mcp/resource-tools Reference for `list_resources` and `read_resource`, which let AI clients that can't read MCP resources directly list and read Biohub MCP Skill files. Use these tools when your client can't list or read MCP resources directly, for example to load a [Skill](/biohub-mcp/skills/overview). They return the same resources as native MCP resource requests, and they work as soon as your client has signed in, like every other Biohub MCP tool. | Tool | Use it to | | - | - | | [`list_resources`](#list-resources) | List every resource the server publishes, without reading any. | | [`read_resource`](#read-resource) | Read one resource by its exact URI. | ## List resources `list_resources` takes no arguments and returns the complete catalog without reading any resource content. | Field | Description | | - | - | | `resources` | MCP descriptors for every resource: each Skill file, and the [structure viewer app](/biohub-mcp/structure-viewer#the-viewer-app). | | `resources[].uri`, `name` | The exact resource URI and name. | | `resource_templates` | MCP descriptors for parameterized resources. Biohub MCP publishes none, so this list is empty. | | Descriptor metadata | `title`, `description`, `mimeType`, and `_meta`, when available. Skill files carry their version and hashes in `_meta`. | The result is complete or an error, with no pagination or truncation. Listing starts no compute, and the tool is marked read-only. ## Read resource | Input | Type | Required | Constraints | | - | - | - | - | | `uri` | string | Yes | 1 to 65,536 characters. Use an exact URI from `list_resources` or a Skill page, such as `skill://waveorder-tutorial/SKILL.md`. | The result uses the MCP resource-read format: | Field | Description | | - | - | | `contents` | Resource content items. | | `contents[].uri` | The requested resource URI. | | `contents[].mimeType` | The content MIME type, when available. | | `contents[].text` | The complete text of a text item. | | `contents[].blob` | Base64-encoded content of a binary item. | | `_meta`, `contents[]._meta` | Published result and content metadata, when available. | Both tools return structured content and the same JSON as text. Neither tool fetches web pages or reads files on your computer. `read_resource` starts no compute when it reads a Skill file. It is marked read-only: `readOnlyHint` true, `destructiveHint` false, `idempotentHint` true, and `openWorldHint` false. ## Limits A `list_resources` or `read_resource` result is limited to 128 KiB (131,072 bytes), counting both copies of the result, JSON escaping, and metadata. A larger result returns `resource_too_large` with `size_bytes` and `max_bytes`, and no partial content. ## Errors | Code | What to do | | - | - | | `not_found` | Copy the exact URI from `list_resources`. | | `resource_too_large` | Read the resource through your client's own MCP resource support. | The tool schema rejects invalid input. ## Example prompts * List the Biohub MCP resources without reading them. * Use `read_resource` to read `skill://waveorder-tutorial/SKILL.md` and tell me what the Skill needs on my computer. * Read `skill://waveorder-tutorial/_manifest` and list the files it publishes. # Biohub MCP security, privacy, and data handling Source: https://docs.biohub.ai/biohub-mcp/security Follow best practices to use the Biohub MCP safely. ## Connect to the real server The only address is: ```text theme={null} https://biohub.ai/mcp ``` Check the hostname before you add it to a client. Don't connect through a shortened link, an unknown proxy, or a directory listing that points somewhere else. ## Sign in only on the Biohub sign-in page Your client opens the Biohub sign-in page in your browser the first time it connects. Before you enter your email address or password, check the address bar. Sign in only on `biohub.ai`, or on `clerk.evolutionaryscale.ai`, the address of Clerk, the service that runs Biohub sign-in. If a sign-in page has any other address, close it. * You don't need an API key for Biohub MCP. Biohub API keys are for calling the Biohub API from your own code, not for MCP. * Never paste a token, key, or password into a prompt, a server URL, a client configuration file, a screenshot, or a bug report. Your client keeps the sign-in for you and sends it only to Biohub MCP. * If a web page, a tool result, or a message asks you for a Biohub token or key, don't provide one. Signing in tells Biohub MCP which account sends each request, and lets it check that the account has a verified email address. Biohub MCP doesn't pass your sign-in on to the ESM Atlas or to outside databases. For complexes, folds, and ESMC scoring, it calls the Biohub Platform for your account without passing on your sign-in. When you stop using a client, remove Biohub MCP from it, or sign out, such as with `codex mcp logout biohub` in Codex. ## Treat tool output as untrusted data Tool results include text from other sources, such as UniProt function descriptions, ESM Atlas annotations, and SAE feature descriptions. This text can be wrong or misleading, and it can contain instructions meant to change what your assistant does. * Keep your own instructions in charge of the task. * Don't let text inside a result ask for credentials, change your settings, or contact other systems. * Review the follow-up calls your assistant proposes before you approve them. * Check surprising claims against the source record, such as the UniProt entry. ## Where your queries go Each tool sends only what it needs to the services behind it. | Tool | Service | What it sends | | - | - | - | | `esm_atlas_search_uniprot` | UniProt | Your query text | | `esm_atlas_lookup_accession` | UniProt (for UniParc) or EMBL-EBI MGnify, depending on the accession | The accession | | `esm_atlas_get_protein_details` | ESM Atlas | A hash that identifies the sequence, and the sequence itself if the ESM Atlas doesn't have it | | `esm_atlas_search_similar_protein_clusters` | ESM Atlas | The sequence | | `esm_atlas_get_cluster_info` | ESM Atlas | A hash that identifies the sequence | | `esm_atlas_get_sae_feature_detail` | ESM Atlas | The feature number | | `ui_show_structure`, one protein | ESM Atlas | A hash that identifies the sequence, and the sequence itself if a structure must be predicted | | `ui_show_structure`, a complex | Biohub Platform, as your Biohub account, which is billed for the fold | Each entity's sequence, CCD code, or SMILES string, and how many copies of it | | `esmfold2_fold_complex`, `esmfold2_fold_max_accuracy` | Biohub Platform, as your Biohub account, which is billed for the fold | Each entity's sequence, CCD code, or SMILES string | | `biohub_get_inference_run` | Biohub Platform, as your Biohub account | The `run_id` | | `esmc_score_mutations`, `esmc_scan_mutation_tolerance` | Biohub Platform, as your Biohub account, which is billed for each ESMC call | The sequence, with one position hidden in each call | | `list_resources`, `read_resource` | None. Biohub MCP serves these resources from its own files. | The resource URI, for `read_resource` | Biohub receives every tool input you send, and handles request data as described in the [Privacy Policy](https://biohub.org/privacy-policy/). Your AI client also sends your prompts, the tool inputs, and the tool results to its model provider, under that client's settings and data policy. Don't send confidential or unpublished sequences unless you're comfortable with them reaching these services and your client's provider. Biohub MCP creates no share links or download URLs for your results. A queued fold creates a run on your Biohub account, which Biohub keeps for 31 days; only your account can read it. The Biohub Platform records the usage of every billed call under your account, as it does for your own API calls. Other results exist only in the response you receive. ## Guardrails The ESM Atlas has [guardrails](/learn/guides/esm-atlas#guardrails) that restrict queries related to controlled pathogens and toxins. A blocked request returns `restricted`, and a similarity search reports withheld hits in `restricted_count`. The Biohub Platform can also refuse a fold or ESMC request for your account, which returns `restricted`. Don't try to work around a guardrail, for example by rephrasing or trimming a sequence. ## Results are predictions Treat results as experimental validation, and confirm anything important in the lab or against curated sources. ## Terms and policies Your use of Biohub MCP is covered by the Biohub [Terms of Use](https://biohub.org/terms-of-use/), [Privacy Policy](https://biohub.org/privacy-policy/), and [Acceptable Use Policy](https://biohub.org/acceptable-use-policy/). # Biohub MCP Skills Source: https://docs.biohub.ai/biohub-mcp/skills/overview Learn how to use the Biohub MCP to run packages like WaveOrder and TCR-Workbench. A Skill is a set of instructions along with any supporting files and scripts that your AI client reads and follows from the Biohub MCP. Skills run commands from where your AI client runs them, which is typically from your own computer. Like the rest of Biohub MCP, Skills are available once your client signs in with a free Biohub account. > [!WARNING] > > Your client sends your conversation, including any command output it reads, to its model provider. ## Skills available through Biohub MCP ### WaveOrder WaveOrder is an open-source package from the Mehta Lab at Biohub that makes physics-based reconstructions of label-free and fluorescence microscopy data. It enables modular and user-friendly implementations of computational microscopy methods for dynamic imaging across the scales of organelles, cells, and tissues. Its source code and examples are on [GitHub](https://github.com/mehta-lab/waveorder). > [card] [Reconstruct microscopy data](/biohub-mcp/skills/waveorder-tutorial) > > Go from a raw stack or a sample dataset to a tuned reconstruction config. > [card] [Visualize a transfer function](/biohub-mcp/skills/waveorder-visualize-otf) > > Compute a config's transfer function and inspect it in napari. ### TCR-Workbench TCR-Workbench analyzes processed TCR and peptide-MHC data on your computer. It can compare peptides for an MHC, investigate TCRs, and screen T-cell repertoires. Its source code is on [GitHub](https://github.com/akdslab/tcr-workbench). > [card] [Analyze TCR data](/biohub-mcp/skills/tcr-workbench) > > Choose, run, and interpret a local TCR-Workbench analysis. > [card] [Set up TCR-Workbench](/biohub-mcp/skills/tcr-workbench-setup) > > Install, configure, and verify a local environment for your machine. ## Start a Skill To start a Skill, use an AI client that can run commands on your computer, such as Claude Code, Codex, or Cursor. Your AI client cannot be read-only. Then, prompt your AI client with a task and the Skill name, such as "Using the Biohub MCP waveorder-tutorial Skill, ...". Your client will then read that Skill's `SKILL.md` first. See the [WaveOrder reconstruction tutorial](/biohub-mcp/skills/waveorder-tutorial) or [TCR-Workbench analysis](/biohub-mcp/skills/tcr-workbench) to get started. See [The assistant ignores a Skill](/biohub-mcp/troubleshooting#the-assistant-ignores-a-skill) for issues with getting your client to use the Skill. ## Skill resources Each Skill has a set of resources, which are files that contain instructions for your AI client to follow. Skills store these resources under the address `skill:///`: | Resource | What it holds | | - | - | | `SKILL.md` | The instructions your client follows. Read it to see what the Skill will ask your client to do, or ask your client to read it if the Skill doesn't start. | | `_manifest` | A list of all the Skill's files. Each file has its size and a SHA-256 hash, a unique code that changes if the file changes. Use this list to see what's in the Skill and to check that no file was changed. | | Supporting files | These are reference files, scripts, and license that comes with the Skill. `SKILL.md` tells your client when to read each one. | Each Skill resource also carries the Skill's version and every file's size and SHA-256 hash in its MCP `_meta`, under `biohub.ai/skill-provenance`. Use that live metadata, not a value copied from these docs, when you need the exact deployed version. If your client can't read MCP resources directly, use the `list_resources` and `read_resource` tools described in the [MCP resource reference](/biohub-mcp/resource-tools) to list and read these files. # Analyze TCR data with TCR-Workbench Source: https://docs.biohub.ai/biohub-mcp/skills/tcr-workbench Learn how the tcr-workbench Skill can choose, run, and interpret local TCR-Workbench analyses of processed TCR and peptide–MHC data. [TCR-Workbench](https://github.com/akdslab/tcr-workbench) can test candidate peptides for a TCR, generate a TCR–conditioned peptide profile, test TCR clonotypes against a peptide panel, and more. Use `tcr-workbench` to run TCR-Workbench analyses of processed human or mouse alpha-beta T-cell receptor (TCR) data on your own computer. The Skill picks the workflow that matches the task you want to do, runs the `python3 tcr.py` launcher, and explains what results are produced by the workflow. > [!NOTE] > > This Skill calls no Biohub tools. > Your AI client runs the TCR-Workbench launcher in a local checkout of [TCR-Workbench](https://github.com/akdslab/tcr-workbench), so it needs a shell on your own computer. > Model workflows also need a completed setup, which the [`tcr-workbench-setup`](/biohub-mcp/skills/tcr-workbench-setup) Skill covers. ## Before you begin Before you run this Skill: * Connect Biohub MCP to a client that can run commands on your computer; see the [Quickstart](/biohub-mcp/quickstart). * Review the commands and downloads before approving them; see [Skills that run commands on your computer](/biohub-mcp/security#skills-that-run-commands-on-your-computer). * Have Python 3.9 or newer on your computer. * Download a local copy of TCR-Workbench on your computer. See [TCR-Workbench setup](/biohub-mcp/skills/tcr-workbench-setup) for instructions. ## Run the Skill Score peptides for an HLA allele Using the Biohub MCP tcr-workbench Skill, score the peptides in peptides.csv against HLA-A\*02:01 with DecoderTCR and tell me which ones rank highest. ## What the Skill guides 1. It checks the local setup with `python3 tcr.py doctor` and hands off to `tcr-workbench-setup` when the environment is missing or lacks what the analysis needs. 2. It chooses the appropriate workflow for your task, such as `pmhc-score` for peptide scores in an MHC context, `tcr-score` for a paired receptor, `repertoire-score` for panel screening, or `screen` for curated reference evidence without model weights. 3. It ingests Cell Ranger V(D)J, AIRR, or paired receptor tables, using the supplied V/J genes and anchored junctions without repairing sequences or inventing cell pairing. 4. It keeps species, MHC class II alpha/beta pairs, model size, device, and precision explicit, and does not switch them silently. 5. It writes each analysis to a new output folder and inspects the result tables, unresolved reasons, QC, and manifests, not only the HTML report. ## Expected result The result includes: * An output folder with an offline `report.html`, the complete result tables, and manifests that record the model, device, precision, and file hashes. * Scored and unresolved counts, with the reason each unresolved row could not be scored. * For score reports, the top-ranked peptides per receptor, MHC, and peptide length, compared with actually scored random peptides. > [!WARNING] > > DecoderTCR scores are uncalibrated model outputs, not binding probabilities. > `Unresolved` means insufficient support, not non-binding, and random reference peptides are not known nonbinders. ## Skill files | Resource | URI | | - | - | | Instructions | `skill://tcr-workbench/SKILL.md` | | File list | `skill://tcr-workbench/_manifest` | | License (MIT) | `skill://tcr-workbench/LICENSE.md` | ## Related documentation * [Skills overview](/biohub-mcp/skills/overview) * [TCR-Workbench setup](/biohub-mcp/skills/tcr-workbench-setup) * [TCR-Workbench on GitHub](https://github.com/akdslab/tcr-workbench) # Set up TCR-Workbench Source: https://docs.biohub.ai/biohub-mcp/skills/tcr-workbench-setup Use the tcr-workbench-setup Skill to install, configure, and verify a local TCR-Workbench environment. [TCR-Workbench](https://github.com/akdslab/tcr-workbench) can test candidate peptides for a TCR, generate a TCR–conditioned peptide profile, test TCR clonotypes against a peptide panel, and more. Use `tcr-workbench-setup` to install TCR-Workbench on a laptop, Mac, workstation, or GPU machine and get your system ready to run analyses. > [!NOTE] > > This Skill calls no Biohub tools. > Your AI client runs the TCR-Workbench launcher in a local checkout of [TCR-Workbench](https://github.com/akdslab/tcr-workbench), so it needs a shell on your own computer, Python 3.9 or newer, and, for model setup, git and network access to GitHub and Hugging Face. ## Before you begin Before you run the Skill: * Connect Biohub MCP to a client that can run commands on your computer; see the [Quickstart](/biohub-mcp/quickstart). * Review the commands and downloads before approving them; see [Skills that run commands on your computer](/biohub-mcp/security#skills-that-run-commands-on-your-computer). * Have Python 3.9 or newer on your computer. ## Run the Skill Install TCR-Workbench on a Mac Using the Biohub MCP tcr-workbench-setup Skill, set up TCR-Workbench on my M2 MacBook so I can score peptides. ## What the Skill guides 1. It starts read-only with `python3 tcr.py doctor` and stops when an install already fits the intended device and model. 2. It chooses CPU, Apple Silicon, or NVIDIA GPU from the machine, and sends Windows users to WSL. 3. It picks the weight source, Hugging Face by default or a shared registry when one is configured, and the DecoderTCR model size the hardware can hold. 4. It runs `python3 tcr.py setup`, which installs DecoderTCR from a pinned commit and configures the chosen runtime and weight source. 5. It diagnoses common failures, including missing git, Hugging Face authentication, and TLS-inspecting proxies, without disabling certificate verification. 6. It verifies the install with `python3 tcr.py doctor --deep` and hands off to the [`tcr-workbench`](/biohub-mcp/skills/tcr-workbench) Skill. ## Expected result The result includes: * A managed `.tcr/` environment in the checkout with the chosen device, model, precision, and weight source. * A `doctor --deep` report that shows a reachable weight source and healthy framework imports. * The next command to run, such as the synthetic example that `python3 tcr.py example` writes. > [!WARNING] > > Model workflows require weight downloads, about 1.3 GB for the default 300M model. > Review the selected device, model, and downloads before approving setup or scoring. ## Skill files | Resource | URI | | - | - | | Instructions | `skill://tcr-workbench-setup/SKILL.md` | | File list | `skill://tcr-workbench-setup/_manifest` | | License (MIT) | `skill://tcr-workbench-setup/LICENSE.md` | ## Related documentation * [Skills overview](/biohub-mcp/skills/overview) * [TCR-Workbench analysis](/biohub-mcp/skills/tcr-workbench) * [TCR-Workbench on GitHub](https://github.com/akdslab/tcr-workbench) # WaveOrder microscopy data reconstruction Source: https://docs.biohub.ai/biohub-mcp/skills/waveorder-tutorial Use the Biohub MCP `waveorder-tutorial` Skill to reconstruct your own microscopy data. [WaveOrder](https://github.com/mehta-lab/waveorder) performs physics-informed reconstructions of labelfree and fluorescence microscopy data, which can sharpen, denoise, improve contrast, and improve interpretability for downstream tasks. Use the `waveorder-tutorial` Skill to run a WaveOrder reconstruction on your own microscopy data, or on a small sample dataset from Zenodo. The Skill works one step at a time and requires additional user input, so expect a conversation rather than a single answer. > [!NOTE] > > This Skill calls no Biohub tools, so none of your microscopy data reaches Biohub. > Your AI client runs the `wo` command, napari, and the Skill's scripts on your own computer. > A first reconstruction usually takes a couple of hours of tuning. ## Before you begin Before you run the Skill, ensure you have the following set up: * Biohub MCP connected to a client that can run commands on your computer, such as Claude Code, Codex, or Cursor. See [Quickstart](/biohub-mcp/quickstart) for setup instructions. * [uv](https://docs.astral.sh/uv/) installed. The Skill uses to install WaveOrder and napari and to run its scripts. * Computer with a display. The Skill displays results in a napari window. * Appropriate dataset. WaveOrder works best on volumetric labelfree and fluorescence microscopy data acquired from weakly scattering samples, which means relatively thin and transparent biological specimens. Data can be in TIFF, NumPy, or plain zarr formats. You can also let the Skill download its sample dataset to demonstrate the reconstruction. ## Run the Skill Try WaveOrder on its sample data Using the Biohub MCP waveorder-tutorial Skill, I want to try waveorder but I don't have any data yet. Can you show me what it does? Reconstruct your own data Using the Biohub MCP waveorder-tutorial Skill, help me reconstruct the microscopy data at (path to your dataset). If your client answers without the Skill, ask it to read `skill://waveorder-tutorial/SKILL.md` and follow it, or see [The assistant ignores a Skill](/biohub-mcp/troubleshooting#the-assistant-ignores-a-skill). ## What the Skill guides 1. It explains what WaveOrder does, checks that it suits your sample, and installs WaveOrder and napari with uv once you agree. 2. It requires the dimensions, contrast type, voxel size, and imaging conditions of the data, one at a time and starting from the file's metadata. It stops if the data is a single 2D image, because WaveOrder needs a Z stack. 3. It converts TIFF, NumPy, or plain zarr data to the OME-Zarr format. It then crops one position and one time point (and one cell when it is much smaller than the field of view) into `roi.zarr` for fast iteration. 4. It drafts 2D or 3D phase or fluorescence configs, including both signs of `invert_phase_contrast` for label-free data. 5. It tunes the forward model on `roi.zarr` with parameter sweeps shown side by side in napari, and raises regularization last. 6. It tests the tuned config on other positions, tries automatic tuning for parameters that drift, and estimates what the full dataset needs. ## Expected result The result of your Skill exploration includes: * A working folder with the converted data, draft configs, sweeps, and the final config. * For each config parameter, where its value came from: metadata, you, a manual sweep, or automatic tuning. * A wall-time, memory, and storage estimate for reconstructing the full dataset. > [!WARNING] > > The Skill displays every result in napari, but does not provide an evaluation of the results. ## What runs on your computer This Skill requires a few commands and downloads to be run on your computer and include the following: * If the `wo` command is missing, the Skill installs `waveorder[all]`, which includes napari, with `uv pip install`. * For the sample data, it downloads a brightfield defocus dataset of about 24 MB from Zenodo into `~/.waveorder_tutorial_data`. * It saves a copy of each bundled script it needs, such as the OME-Zarr converter and the parameter sweep, into your working folder and runs it there. ## Skill files | Resource | URI | | - | - | | Instructions | `skill://waveorder-tutorial/SKILL.md` | | File list | `skill://waveorder-tutorial/_manifest` | | License (BSD 3-Clause) | `skill://waveorder-tutorial/LICENSE.md` | ## Related documentation * [WaveOrder transfer function tutorial](/biohub-mcp/skills/waveorder-visualize-otf) * [Skills overview](/biohub-mcp/skills/overview) * [Skills that run commands on your computer](/biohub-mcp/security#skills-that-run-commands-on-your-computer) * [WaveOrder on GitHub](https://github.com/mehta-lab/waveorder) # WaveOrder transfer function Source: https://docs.biohub.ai/biohub-mcp/skills/waveorder-visualize-otf Use the Biohub MCP `waveorder-visualize-otf` Skill to compute a WaveOrder config's transfer function on your own computer and view it in napari. [WaveOrder](https://github.com/mehta-lab/waveorder) performs physics-informed reconstructions of label-free and fluorescence microscopy data, which can sharpen, denoise, improve contrast, and improve interpretability for downstream tasks. Use this Skill to run `waveorder-visualize-otf` to see how a WaveOrder config's numerical aperture, wavelength, and pixel size affect its transfer function before you complete any downstream reconstruction tasks. > [!NOTE] > > This Skill calls no Biohub tools, so none of your data reaches Biohub. > Your AI client runs the `wo` command and napari on your own computer. ## Before you begin Before you run the Skill, ensure you have the following set up: * Biohub MCP connected to a client that can run commands on your computer, such as Claude Code, Codex, or Cursor; see the [Quickstart](/biohub-mcp/quickstart). * [uv](https://docs.astral.sh/uv/) installed. * Computer with a display for napari. * WaveOrder reconstruction config, such as one the [WaveOrder reconstruction tutorial](/biohub-mcp/skills/waveorder-tutorial) created. * One OME-Zarr position with your data's ZYX shape. The Skill reads only its shape, so any dataset of that shape works. ## Run the Skill Show the transfer function for a config Using the Biohub MCP waveorder-visualize-otf Skill, show me the transfer function for my config phase\_3d.yml using the data at data.zarr/0/0/0. If your client answers without the Skill, ask it to read `skill://waveorder-visualize-otf/SKILL.md` and follow it, or see [The assistant ignores a Skill](/biohub-mcp/troubleshooting#the-assistant-ignores-a-skill). ## What the Skill guides 1. It requires you to provide a reconstruction config and one OME-Zarr position. 2. It runs `wo compute-tf` to write the transfer function to `./_otf.zarr`, so results for different configs sit side by side. 3. It opens the result with `wo view` without blocking the client. To compare settings, give it several configs: the Skill will compute each transfer function and open them in one napari window. ## Expected result The result of your Skill exploration includes: * The path to `./_otf.zarr`. * A napari window with the real and imaginary parts of the transfer function, with DC at the center. * For a 2D phase config, the absorption and phase transfer functions, which `wo view` rebuilds from the stored singular system. ## What runs on your computer The Skill runs `wo compute-tf` and `wo view` in your working folder. If `wo` isn't installed, it runs both through `uvx --from "waveorder[all]"` instead of installing WaveOrder. ## Skill files | Resource | URI | | - | - | | Instructions | `skill://waveorder-visualize-otf/SKILL.md` | | File list | `skill://waveorder-visualize-otf/_manifest` | | License (BSD 3-Clause) | `skill://waveorder-visualize-otf/LICENSE.md` | ## Related documentation * [WaveOrder reconstruction tutorial](/biohub-mcp/skills/waveorder-tutorial) * [Skills overview](/biohub-mcp/skills/overview) * [Skills that run commands on your computer](/biohub-mcp/security#skills-that-run-commands-on-your-computer) * [WaveOrder on GitHub](https://github.com/mehta-lab/waveorder) # Biohub MCP structure viewer Source: https://docs.biohub.ai/biohub-mcp/structure-viewer Show a protein or fold a complex with `ui_show_structure`, set `view_options`, and get a structure viewer plus an optional PNG preview. The tool `ui_show_structure` shows a protein, or a complex of proteins, DNA, RNA, and small molecules, from its sequence. In clients that support MCP Apps, it opens an interactive structure viewer. It returns a PNG preview only when the call sets `include_png` to `true`. > [!NOTE] > > If you run this tool on one protein, it uses the free ESM Atlas tool. Running this tool on a complex uses the folding tool, which is then billed to your Biohub account, as [Complexes](#complexes) describes. Show me the structure of GFP, colored by confidence, with Ser65, Tyr66, and Gly67 highlighted. Show me the structure of GFP, colored by confidence, with Ser65, Tyr66, and Gly67 highlighted. ![The structure viewer showing GFP as a dark blue cartoon beta barrel, with Style and Colored By menus, the pTM and mean pLDDT, the sequence, and highlighted residues A:65 S, A:66 Y, and A:67 G.](https://mintcdn.com/biohub-8940d923/bSpHKvTLEcBtBXJO/images/biohub-mcp/structure-viewer-light.png?fit=max\&auto=format\&n=bSpHKvTLEcBtBXJO\&q=85\&s=06cad3c31ad26b1ed864a9211b3e1971) GFP in the structure viewer, colored by confidence, with its chromophore residues highlighted. You can use the protein name, give its UniProt accession, or paste its sequence to use the viewer. ## How a protein view is built For one protein with one copy: **1. Look up the sequence** The server looks up the exact sequence in the ESM Atlas and uses the stored structure if there is one. **2. Predict a structure on a miss** If the ESM Atlas has no stored structure and the sequence is 700 residues or fewer, it predicts one for this request. A longer sequence without a stored structure returns `sequence_too_long_to_fold`. **3. Deliver the structure** The server sends the exact PDB file, with per-residue confidence, to the viewer. A view of a stored structure takes about 2 seconds without a PNG preview and 4 to 8 seconds with one. A prediction on a miss takes longer. ## Inputs | Name | Type | Required | Limits | Default | | - | - | - | - | - | | `entities` | array | Yes | 1 to 36 molecules, described below | | | `view_options` | object | No | See below | Cartoon overview, colored as described below | | `include_png` | boolean | No | `true` or `false` | `false` | ### entities Each entry in `entities` is one distinct molecule, in order: | Field | Type | Applies to | Description | | - | - | - | - | | `type` | string | All | `protein`, `dna`, `rna`, or `ligand`. | | `sequence` | string | `protein`, `dna`, `rna` | One chain, 1 to 4,096 letters. Proteins use the 20 standard amino acids, `X` for unknown, and `B`, `U`, `Z`, and `O`. DNA uses `A`, `C`, `G`, `T`, and `N`, and RNA uses `A`, `C`, `G`, `U`, and `N`, both written 5' to 3'. Spaces and line breaks are removed, and letters are made uppercase. | | `ccd` | string | `ligand` | A [PDB Chemical Component Dictionary](https://www.wwpdb.org/data/ccd) code of 1 to 5 letters or digits, such as `ATP`. | | `smiles` | string | `ligand` | A SMILES string of up to 2,000 characters, such as `CC(=O)Oc1ccccc1C(=O)O` for aspirin. | | `copies` | integer | All | Identical copies of the entity, each its own chain, from 1 to 36. Defaults to `1`. | To show one protein, give one entry: ```json theme={null} { "entities": [{ "type": "protein", "sequence": "MKTAYIAKQRQISFVKSHFSRQ" }] } ``` One protein can be up to 4,000 residues. The ESM Atlas matches the exact sequence, so a variant or trimmed sequence counts as a different protein. Anything else is a [complex](#complexes). Give a ligand either `ccd` or `smiles`, not both. Give each strand of a DNA duplex as its own entity. ### include\_png By default, the server doesn't render the structure, and the result has no image. Set `include_png` to `true` when your assistant needs to see the structure itself, or when your client can't show the interactive viewer. The server then renders a PNG of the starting view and adds it to the result, which adds several seconds to the call. ### view\_options Display settings change only what you see. They never change the PDB file. | Field | Type | Values | Default | | - | - | - | - | | `representation` | string | `cartoon` or `surface` | `cartoon` | | `orientation` | string | `overview`, `hotspot-facing`, `opposite`, or `side` | `overview` | | `color_by` | string | `chain` or `confidence` | `confidence` when the structure has confidence scores, otherwise `chain` | | `highlights` | array | Up to 32 unique residues, described below | `[]` | | `visible_chain_ids` | array of strings | 1 to 128 unique one-character chain IDs | All chains | | `camera` | object | An exact camera pose, described below | `null` | `hotspot-facing` turns the highlighted residues toward you, `opposite` shows the other side, and `side` looks from 90 degrees. `hotspot-facing` needs at least one highlight or a `camera`. Each entry in `highlights` names a residue by its number in the structure: | Field | Type | Required | Description | | - | - | - | - | | `chain_id` | string | Yes | One-character chain ID. ESM Atlas structures use chain `A`; a complex uses the [chain labels](#chain-labels) below. | | `author_residue_number` | integer | Yes | Residue number from -999 to 9999. ESM Atlas structures number residues from 1. | | `insertion_code` | string | No | Zero or one character. Defaults to empty. | | `expected_residue` | string | No | Uppercase one- or three-letter code, such as `W` or `TRP`. The call fails if the structure has a different residue there. | | `color` | string | No | Hex color in the form `#RRGGBB`. Defaults to the viewer's highlight palette. | This example colors GB1 by confidence and turns Trp43 toward you: ```json theme={null} { "entities": [ { "type": "protein", "sequence": "MTYKLILNGKTLKGETTTEAVDAATAEKVFKQYANDNGVDGEWTYDDATKTFTVTE" } ], "view_options": { "color_by": "confidence", "orientation": "hotspot-facing", "highlights": [ { "chain_id": "A", "author_residue_number": 43, "expected_residue": "W" } ] } } ``` The `camera` object sets an exact camera pose in angstroms. It needs `position`, `target`, and `up` (each three numbers), `radius`, and `radius_max`. `projection` defaults to `orthographic`, `fov` to about 0.785 radians, and `viewport` to 1024 by 768 pixels. When the server rendered a preview, the result includes the camera it used, even if the image was then dropped for size. You can pass that camera back to reproduce the view. Otherwise the result returns `camera` as you sent it, which is `null` by default, and the viewer computes the orientation itself. When you set `camera`, it replaces the `orientation` preset. ## What the tool returns Every successful result contains: * A text block with a JSON summary of the view. * A PNG preview, when `include_png` is `true` and rendering succeeds. * The same summary as structured content. * The PDB file and per-residue annotations, delivered to the viewer app in the result metadata rather than in the text your assistant reads. | Field | Description | | - | - | | `descriptor.filename` | File name: `atlas-.pdb` for one protein, or `complex-.pdb` for a complex. | | `descriptor.size_bytes`, `descriptor.sha256` | Size and SHA-256 of the exact PDB file delivered with this result. | | `descriptor.source.kind` | `catalog` for a structure already stored in the ESM Atlas, or `prediction` for one predicted for this request. A complex is always `prediction`. All are model predictions. | | `descriptor.source.folded_on_miss` | For one protein, `true` when the structure was predicted for this request. | | `descriptor.source.protein_hash`, `model` | For one protein, the ESM Atlas content hash of the sequence, and the model name when the ESM Atlas reports one. | | `descriptor.source.provider`, `model` | For a complex, `bhp` and the model that folded it. | | `view_options` | The view used, with `camera` as described [above](#view_options). | | `preview_status` | `not_requested` when `include_png` is `false`, `available` when the result has a PNG preview, or `unavailable` when a requested preview couldn't be returned. | | `preview_failure` | Why a requested preview is missing, such as `rate_limited` when the renderer is busy or `response_size_limit` when the image didn't fit. `null` otherwise. | | `inspection_status` | `requires_visual_assessment` when there is a preview, `image_unavailable` otherwise. | | `entities` | One entry per entity you sent, with its `type`, its `chain_ids`, its `length` in residues or nucleotides per chain (`null` for a ligand), and its `ligand`: the CCD code, `SMILES` for a SMILES ligand, or `null` for a polymer. | | `ptm` | Predicted TM-score of the whole structure, from 0 to 1, or `null` when unavailable. | | `iptm` | Interface predicted TM-score between chains, from 0 to 1, or `null` for a single chain. | | `warnings` | Notes about the structure file, if any, such as a renamed ligand. | A preview that fails doesn't fail the call. The viewer receives the structure whether or not there is a preview. Without one, your assistant has no image to look at, so it shouldn't make visual claims about the structure. ## The viewer app The interactive viewer is an MCP App resource that the tool links to in its metadata. | Property | Value | | - | - | | URI | `ui://biohub-public/structure-viewer/v1` | | MIME type | `text/html;profile=mcp-app` | | Name | `structure_viewer` | The app loads no external resources, and it asks the host only for clipboard access. ## What your client shows * Clients that support MCP Apps render the interactive structure viewer inline. ChatGPT shows it in developer mode. * Other clients show only the text result, unless the call sets `include_png` to `true` and the client displays images. If your client doesn't show the viewer, ask your assistant for a PNG preview. In the viewer you can: * Rotate and zoom the structure with your mouse or trackpad. * Switch **Style** between cartoon and surface, and **Colored By** between confidence and chain, or, for one protein, one of its ten strongest SAE features when the ESM Atlas has them. * Show or hide chains. * Click residues to highlight them, up to 32, zoom to a highlighted residue, and clear highlights again. * Reset the camera to a straight-on view of the whole structure. * Read and copy the sequence, which the viewer shows alongside the 3D model.