Show an HTML preview
When your agent builds a web page for people to look at, such as a mock-up, a small interactive demo or a rendered report, show it as a card instead of pasting source. The page runs in a sandbox inside the conversation. The tool is show_html_preview, part of the Streams MCP server.
What the tool does
Section titled “What the tool does”show_html_preview posts one card as a message from your agent, with a one-line text caption for readers that cannot render the card.
The card shows the title and controls, without a warning strip or author attribution. Older desktop and iOS apps without the updated preview isolation show Preview unavailable instead of loading the page. Update the app to view it.
- Display only. Nothing is answered and nothing comes back. The call returns at once, viewing the card never starts a turn, and the card does not count toward the forms and boards creation limit.
- One self-contained document, uploaded first. The page is a file you upload, not a tool argument, so it can be as large as a
text/htmlupload (10 MB). Put CSS, JavaScript and data inline. Images, fonts, scripts and styles must be inline (data:orblob:URLs): the page cannot load anything from another host, so a CDN link or a remote image shows nothing. Links in the page do nothing: it cannot open a new window or send its frame to another address. There is no “open in a new tab” for a preview, because a bare tab would not have that protection. - Sandboxed. The page runs with scripts allowed and without access to Streams, cookies, storage or forms. It cannot call Streams or any server of yours with a request, load resources from another host or open new windows, and Streams sends nothing from the page back to you or the agent. Its frame can only show the page itself. Two things remain possible, so people are told not to type secrets into a preview: a page can imitate a sign-in form, and browser features outside page rules (WebRTC is the known one) can carry a small amount of data to a host. Do not collect secrets in a preview.
- Shown as a file. The card links your uploaded file to the stream, so its members can open it, under the same permissions and virus scan as any file. Any ready
text/htmlfile you can read works, including one a person shared with you. Nothing is copied. - Safe to retry.
requestIdis a UUID you generate once per card. Calling again with the samerequestIdand the same content returns the card already posted (created: false). The samerequestIdwith different content is refused with409 chat.html_preview_request_conflict, and so is a retry after the card’s message was deleted. - Rate limit. At most 5 new cards per minute per stream and agent:
429 chat.html_preview_rate_limitedwith aRetry-Afterheader. Retries of an existing card do not count. Uploads have their own limit atcreate_upload(429 files.rate_limited,Retry-Afterset). - Deleting the message removes the card.
Upload the page first
Section titled “Upload the page first”create_uploadwithcontentType: "text/html", afileNameand the size in bytes. It returnsassetId,uploadIdand a presigned URL per part.PUTeach part’s bytes to its URL, outside MCP, and keep theETagresponse header of each.complete_uploadwith theassetId,uploadIdand the parts. The asset is ready when it returns.- Call
show_html_previewwith thatassetId.
An agent that cannot make an HTTP PUT cannot show a page. The former html argument is gone: a call that sends it is refused with 400 kernel.validation_failed and a message that repeats these steps.
| Field | Type | Notes |
|---|---|---|
requestId |
UUID | Generate once per card; reuse it on a retry. |
streamId |
UUID | The stream to post in. Your agent must be a member. |
threadSessionId |
UUID, optional | Put the card in that thread, by its session id. |
replyToMessageId |
UUID, optional | Put the card in the thread of that message. With threadSessionId too, both must name the same thread. |
title |
string, optional | Up to 80 characters. Names the card in the text caption. |
assetId |
UUID | A ready text/html file you can read, from create_upload and complete_upload. |
Result
Section titled “Result”{ interactionId, messageId, created }. Read the card back with get_ui_interaction: the interaction is always submitted, with input { title?, assetId }. Fetch the bytes with get_asset_url if you need them. Message history and search never carry the asset id or the page.
Errors
Section titled “Errors”| Status | Code | Meaning |
|---|---|---|
| 400 | kernel.validation_failed |
No assetId, the old html argument, an unknown field or a bad id. |
| 400 | chat.html_preview_invalid_asset |
The file is missing or unreadable (not_found), unfinished (not_ready), blocked by the scan (blocked) or not text/html (unsupported_type); see details.reason. |
| 409 | chat.html_preview_request_conflict |
The requestId was used for different content. |
| 429 | chat.html_preview_rate_limited |
More than 5 new cards in a minute in this stream. |
| 429 | files.rate_limited |
Too many file uploads started this minute (at create_upload). |