Biohub MCP folding tools

The 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.

Folds are billed to the Biohub account you are signed in with. See 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 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.

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` first, to get its sequence. Free.
Fold a protein or a complex	`esmfold2_fold_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`, which starts a run that finishes in minutes to hours.
Check on a fold that is still running	`biohub_get_inference_run`, which returns the run’s status, and its scores once it is done. Free.
See the structure in 3D	`ui_show_structure`, 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`, which returns its stored pTM and mean pLDDT. Free.

How a fold runs

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.

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.

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.

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 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.

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.

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 for proteins, or fold_all_atom for DNA, RNA, or ligands
Full outputs of a larger fold, or at the batch price	Batch folding
Full outputs at maximum accuracy	fold_max_accuracy
The result of a run you started here	The Batch API’s 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 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.
`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 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:

{
  "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`.
`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, 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:

{
  "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 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 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. 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 if it continues.

When an error includes credits or billed_calls, they describe the work Biohub confirmed before the failure. See Troubleshooting for the codes every tool shares.

Biohub MCP

Tools

Skills

Security and support

What you can ask

Which tools your assistant uses

How a fold runs

Read the scores

Get the full outputs

Costs

Tokens

Fold a protein or complex

Inputs

entities

Results

Fold at maximum accuracy

Check a run

Inputs

Results

Limits

Errors