> ## 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 structure viewer: Mol* protein views

> Show a protein structure with the Biohub MCP ui_show_protein_structure tool, set view_options, and learn what the Mol* app and PNG preview return.

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

<Prompt description="View a protein structure">
  Show me the structure of this protein: \[paste your sequence].
</Prompt>

## How a view is built

<Steps>
  <Step title="Look up the sequence">
    The server looks up the exact sequence in the ESM Atlas and uses the stored structure if there is one.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Render and deliver">
    The server renders a PNG preview and sends the exact PDB file, with per-residue confidence, to the viewer.
  </Step>
</Steps>

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](/biohub-mcp/esm-atlas-tools#sequence-inputs).

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

```json theme={null}
{
  "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](https://creativecommons.org/licenses/by/4.0/), 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](/learn/guides/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](/biohub-mcp/troubleshooting#error-codes) for what to do about each one.