Biohub MCP structure viewer: Mol* protein views

ui_show_protein_structure shows a protein from its amino-acid sequence. It returns a PNG preview and, in clients that support MCP Apps, an interactive Mol* viewer. Changing the view inside the viewer doesn’t call the server again.

View a protein structure

How a view is built

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.

Render and deliver

The server renders a PNG preview and sends the exact PDB file, with per-residue confidence, to the viewer.

In our tests, a view took 15 to 25 seconds, with or without a prediction. Nothing is saved: there is no structure ID or download link, and calling the tool again may compute again. A second prediction of the same sequence can have slightly different coordinates.

Inputs

Name	Type	Required	Limits	Default
`sequence`	string	Yes	1 to 4,000 residues; 700 or fewer to predict on a miss
`view_options`	object	No	See below	Cartoon overview colored by chain

The sequence follows the same rules as the ESM Atlas tools.

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

{
  "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 Mol* 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. The result includes the camera used for the preview, so you can pass it back to reproduce a view. 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 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`.
`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. Both are model predictions.
`descriptor.source.folded_on_miss`	`true` when the structure was predicted for this request.
`descriptor.source.protein_hash`, `model`	ESM Atlas content hash of the sequence, and the model name when the ESM Atlas reports one.
`view_options`	The view used, including the preview’s camera.
`preview_status`	`available` or `unavailable`.
`preview_failure`	Why the preview is missing, such as `rate_limited` when the renderer is busy or `response_size_limit` when the image didn’t fit.
`inspection_status`	`requires_visual_assessment` when there is a preview, `image_unavailable` otherwise.
`warnings`	Notes about the structure file, if any.

A missing preview doesn’t fail the call. The viewer still receives the structure, but 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	`protein_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 Mol* viewer inline. ChatGPT shows it in developer mode.
Other clients show the text result, and the PNG preview if they display images.

In the viewer you can:

Switch Style between cartoon and surface, and Color between chain and confidence.
Choose a View: overview, selected patch, opposite, or side.
Show or hide chains.
Click residues to highlight them, up to 32, and clear them again.
Read the sequence, which the viewer shows alongside the 3D model.

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, Download PDB is disabled, no image download is offered, and the viewer notes that the client doesn’t support file downloads.
Every PDB file, stored or predicted, is released under the CC BY 4.0 license, as noted in its header.

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

Limits

Limit	Value	When exceeded
Sequence length	4,000 residues	`invalid_input`
Prediction on a miss	700 residues	`sequence_too_long_to_fold`
PDB size for viewing	2 MiB	`dependency_unavailable`
Atoms for viewing	20,000	`dependency_unavailable`
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`	The sequence is invalid, a highlighted residue or visible chain isn’t in the structure, `expected_residue` doesn’t match, or `hotspot-facing` has no highlight.
`sequence_too_long_to_fold`	No stored structure, and the sequence is over 700 residues. The error includes `actual_length` and `max_length`.
`restricted`	ESM Atlas guardrails blocked the request.
`rate_limited`	The ESM Atlas is rate limiting lookups or predictions. The error includes `retry_after_seconds`; wait at least that long before calling again.
`dependency_unavailable`	The structure is over the viewing limits, or the ESM Atlas is unavailable or sent an unusable response. A renderer failure doesn’t cause this error: the call still succeeds with `preview_status` set to `unavailable`.
`indeterminate`	The deadline passed or a prediction’s outcome is unknown. Don’t retry right away.
`resource_too_large`	Even without the preview, the result is over 6 MiB.

See Troubleshooting for what to do about each one.

​How a view is built

​Inputs

​view_options

​What the tool returns

​The viewer app

​What your client shows

​Export

​Limits

​Errors