Skip to content

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.

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/html upload (10 MB). Put CSS, JavaScript and data inline. Images, fonts, scripts and styles must be inline (data: or blob: 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/html file you can read works, including one a person shared with you. Nothing is copied.
  • Safe to retry. requestId is a UUID you generate once per card. Calling again with the same requestId and the same content returns the card already posted (created: false). The same requestId with different content is refused with 409 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_limited with a Retry-After header. Retries of an existing card do not count. Uploads have their own limit at create_upload (429 files.rate_limited, Retry-After set).
  • Deleting the message removes the card.
  1. create_upload with contentType: "text/html", a fileName and the size in bytes. It returns assetId, uploadId and a presigned URL per part.
  2. PUT each part’s bytes to its URL, outside MCP, and keep the ETag response header of each.
  3. complete_upload with the assetId, uploadId and the parts. The asset is ready when it returns.
  4. Call show_html_preview with that assetId.

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.

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

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