make_surface_url
Render an A2UI payload in the CALLER'S OWN environment. Pass renderer_url (your deployed renderer /exec) and get a live URL + the catalogs it declares. Omit renderer_url to get the encoded fragment + BYO guidance. We host nothing and never see your content.
NEVER hand-write your own gzip/base64 encoding for the ?p= URL, in ANY language, even as a "just this once" fallback. This is the single most common cause of "could not decompress gzip" — a self-written encoder with one wrong flag (wrong wbits, standard vs. urlsafe base64, un-stripped padding) produces a broken URL at ANY size, not just large ones. Always call this tool again — never substitute your own implementation.
SIZING IS AUTOMATIC — you do not need to estimate, count characters, or decide whether to split. Call this tool ONCE with your FULL, unsplit payload. If it fits, you get back url (and nothing else to do). If it does not fit the real size ceiling, the tool SPLITS IT FOR YOU server-side (at natural heading boundaries) and returns auto_split: true plus a pages array of independent URLs — present that list to the user (e.g. as numbered links) instead of the single url. Never pre-split your content before the first call; always send everything in one call and let the response tell you what happened.
GRADUATE substantial surfaces with emit_deployment instead (no size limit at all) when you want a standing app rather than a shareable link.
IF A RENDER CHECK REPORTS "could not decompress gzip" / "Render error" / "invalid distance too far back" on a URL this tool returned: STOP. Do NOT call this tool again with the SAME unchanged payload — re-call it with the SAME payload once to confirm, and if it still fails, use emit_deployment instead. Never fall back to a hand-written encoding script.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"payload": "<payload>"
},
"name": "make_surface_url"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| payload | Yes | The A2UI payload to encode into a ?p= URL: {title, theme, blocks:[...]}. Send it whole; oversize payloads are split for you. | |
| renderer_url | No | your renderer /exec (BYO). Omit for fragment + guidance. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Live renderer URL (present when renderer_url was given; the first page when split). | |
| note | No | Guidance for the caller. | |
| size | No | Present when the URL is large: url_length, warning and recommendation. | |
| pages | No | One entry per page, each with a url. | |
| fragment | No | The ?p= fragment to append to your own renderer (present when renderer_url was omitted). | |
| clipboard | No | Optional ready-made copy commands for the URL (linux, macos, windows) plus a note. | |
| auto_split | No | True when the payload was split into pages. | |
| page_count | No | Number of pages when split. | |
| required_catalogs | Yes | Catalog URIs the payload needs (base catalog first). |