> ## Documentation Index
> Fetch the complete documentation index at: https://docs.biohub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Biohub MCP folding tools

> Fold proteins and complexes with ESMFold2 through Biohub MCP.

The [ESMFold2](https://docs.biohub.ai/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`](https://docs.biohub.ai/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`](https://docs.biohub.ai/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`](https://docs.biohub.ai/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](https://docs.biohub.ai/api/protein/models/fold.md) for proteins, or [fold\_all\_atom](https://docs.biohub.ai/api/protein/models/fold_all_atom.md) for DNA, RNA, or ligands |
| Full outputs of a larger fold, or at the batch price | [Batch folding](https://docs.biohub.ai/api/protein/models/batch_folding.md) |
| Full outputs at maximum accuracy | [fold\_max\_accuracy](https://docs.biohub.ai/api/protein/models/fold_max_accuracy.md) |
| The result of a run you started here | The Batch API's [Status](https://docs.biohub.ai/api/protein/models/batch_status.md) 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](https://docs.biohub.ai/api/protein/models/response-formats.md) 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](https://docs.biohub.ai/api/protein/models/batch_folding.md).
  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](https://docs.biohub.ai/biohub-mcp/troubleshooting.md#error-codes) for the codes every tool shares.


## Related topics

- [Biohub MCP ESM Atlas tools](https://docs.biohub.ai/biohub-mcp/esm-atlas-tools.md)
- [Troubleshoot Biohub MCP connections and tool errors](https://docs.biohub.ai/biohub-mcp/troubleshooting.md)
- [Biohub MCP resource tools reference](https://docs.biohub.ai/biohub-mcp/resource-tools.md)
- [Biohub MCP mutation scoring tools](https://docs.biohub.ai/biohub-mcp/mutation-scoring-tools.md)
- [Biohub MCP server](https://docs.biohub.ai/biohub-mcp/overview.md)