Biohub MCP structure viewer

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.

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

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. — GFP in the structure viewer, colored by confidence, with its chromophore residues highlighted.

The structure viewer in dark mode 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. — 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:

Look up the sequence

The server looks up the exact sequence in the ESM Atlas and uses the stored structure if there is one.

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.

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

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

{
  "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-<protein_hash>.pdb` for one protein, or `complex-<first 16 hex digits of the SHA-256>.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.
`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.

Rotating GFP, switching to a surface and back, coloring by an SAE feature, zooming to Tyr66, and resetting the camera.

Below the structure, the viewer shows pTM, mean pLDDT, and Known, the percentage of the protein’s ESM Atlas cluster with Pfam annotations, or a dash when that is unknown. Hover over a residue to see its own values instead. With confidence coloring, residues are dark blue at pLDDT 0.9 or higher, light blue from 0.7, yellow from 0.5, orange below 0.5, and gray where confidence is unavailable.

Export

Download PDB saves the complete original file. The viewer checks its size and SHA-256 before it displays or exports it.
The image download saves a PNG of the current view, keeping its aspect ratio, at up to 1,600 pixels per side and about one megapixel in total.
Both need a client that supports file downloads. Elsewhere, the viewer shows neither Download PDB nor the image download.
Every PDB file from the ESM Atlas, stored or predicted, is released under the CC BY 4.0 license, as noted in its header. A complex’s PDB file has only atom records and no license header.

To get the file again later, call the tool again.

Complexes

Any input other than one protein with one copy is a complex: several chains, copies above 1, DNA, RNA, or ligands. Examples are a protein bound to ATP, a protein on DNA, or a homodimer. The server folds the complex with ESMFold2 on the Biohub Platform and shows it in the same viewer.

Each complex is a new fold billed to your Biohub account. To get scores without the viewer, fold a larger complex, or pay the lower batch price, ask for a fold instead, as Folding tools describes.

Fold and view a protein with ATP

Each complex is sent to the Biohub Platform once, as you, with model esmfold2-fast-2026-05. Your account’s limits and credits apply, exactly as for the fold_all_atom API. The fold must finish within 95 seconds. Nothing is saved: calling the tool again runs and bills a new fold. This example folds a homodimer with one ATP:

{
  "entities": [
    { "type": "protein", "sequence": "MKTAYIAKQRQISFVKSHFSRQ", "copies": 2 },
    { "type": "ligand", "ccd": "ATP" }
  ]
}

Chain labels

Chains are labeled A to Z and then a to j, in the order you list the entities and their copies. In the example, the two protein copies are chains A and B, and ATP is chain C. Residues are numbered from 1 in each chain, and each ligand is a single residue in its own chain. Use these chain IDs and numbers in highlights and visible_chain_ids.

Size limit

The Biohub Platform folds up to 768 tokens in one call. Each protein residue and each DNA or RNA nucleotide is one token, each ligand heavy atom (every atom except hydrogen) is one token, and every copy counts. For example, a 300-residue homodimer with one ATP is 300 × 2 + 31 = 631 tokens, because ATP has 31 heavy atoms. A larger complex returns sequence_too_long_to_fold. Get its confidence scores with esmfold2_fold_complex, or its structure file with Batch folding; both accept up to 4,096 tokens.

Complexes in the viewer

Confidence coloring covers protein, DNA, and RNA residues; ligands stay gray, because their confidence isn’t per residue.
The viewer’s stats show the complex’s pTM and the mean pLDDT of its polymer residues; ipTM is only in the tool result.
A ligand given as SMILES appears as residue LIG.
A PDB residue name holds three characters, so a ligand with a longer CCD code, such as A1A3E, appears as UNL, and warnings says so.
A complex has no ESM Atlas features, so Colored By offers only confidence and chain.

Limits

Limit	Value	When exceeded
One protein’s length	4,000 residues	`invalid_input`
Prediction on a miss	700 residues	`sequence_too_long_to_fold`
Chains in a complex, counting copies	36	`invalid_input`, before any fold
Complex size	768 tokens	`sequence_too_long_to_fold`
Complex fold time	95 seconds	`indeterminate`
PDB size for viewing	2 MiB	`dependency_unavailable`
Atoms for viewing	20,000	`dependency_unavailable` for one protein; `resource_too_large` for a complex, after the fold has run and been billed
Highlights	32	`invalid_input`
Preview rendering	20 seconds	Result without a preview
Complete result	6 MiB	The preview is dropped first, then `resource_too_large`
Tool deadline	120 seconds	`indeterminate`

Errors

Code	Cause
`invalid_input`	An entity breaks the rules above, a complex has more than 36 chains, a highlighted residue or visible chain isn’t in the structure, `expected_residue` doesn’t match, or `hotspot-facing` has no highlight. When the Biohub Platform rejects a complex, the message gives its reason, such as an unknown CCD code.
`sequence_too_long_to_fold`	One protein has no stored structure and is over 700 residues, or a complex is over 768 tokens. The error includes `actual_length` and `max_length`; for a complex, its message points to the Batch API.
`restricted`	ESM Atlas guardrails blocked the request. For a complex, you aren’t signed in, or the Biohub Platform refused the request for your account, for example because it has no access to the model.
`rate_limited`	The ESM Atlas is rate limiting lookups or predictions, or, for a complex, your account reached a Biohub Platform rate limit or ran out of credits. The error includes `retry_after_seconds`; wait at least that long before calling again.
`dependency_unavailable`	The structure is over the viewing limits, the ESM Atlas is unavailable or sent an unusable response, or the Biohub Platform is unavailable. A renderer failure doesn’t cause this error: the call still succeeds with `preview_status` set to `unavailable`.
`indeterminate`	The deadline passed, or the outcome of a prediction or a complex fold is unknown. A complex fold may have run and been billed. Don’t retry right away.
`resource_too_large`	A folded complex is over 20,000 atoms, or the result is over 6 MiB even without the preview.

See Troubleshooting for what to do about each one.

Biohub MCP

Tools

Skills

Security and support

Biohub MCP structure viewer

How a protein view is built

Inputs

entities

include_png

view_options

What the tool returns

The viewer app

What your client shows

Export

Complexes

Chain labels

Size limit

Complexes in the viewer

Limits

Errors