Sign in
Execution

Render an MCP App widget headlessly

Call an MCP App tool and mount its ui:// widget in real headless Chromium running the production host bridge, then report whether it rendered, what it logged, what it was blocked from fetching, and the widget as an accessibility tree with addressable elements.

Executes the tool, so it has whatever side effects that tool has — the render is what happens afterwards.

Stateless: connect, call, render, read, dispose, all inside one request. Interactive widget sessions are a local-Inspector capability (/api/mcp/widget-session) because they hold a live browser in process, which a no-affinity hosted plane cannot serve.

Each render launches a browser, so the endpoint carries a per-replica concurrency cap and answers 429 when it is full.

post/projects/{projectId}/servers/{serverId}/widgets/render

Path parameters

projectIdstring required

ID of the hosted project that contains the server.

serverIdstring required

ID of the server inside the project.

Request body

toolNamestring required

The MCP App tool to render. A tool that declares no ui:// UI resource is refused (422) rather than run.

parametersobject
includeSnapshotboolean

Return the widget as an accessibility tree with addressable elements. Default true — the reverse of the local Inspector route, because this endpoint's caller is usually a model for which a base64 image is the most expensive way to say nothing.

includeScreenshotboolean

Also return a base64 image. Default false: it is by far the largest field this returns.

injectOpenAiCompatboolean

Mount with the OpenAI Apps compatibility shims instead of the spec-default MCP-UI bridge.

Response

The render verdict and its evidence.

statusstring required

The render verdict, e.g. rendered.

resourceUristring
bridgeInitializedboolean
consoleErrorsstring[]
blockedRequestsstring[]

Requests the render sandbox refused. A widget that renders while every fetch is blocked photographs perfectly and is broken, so this is reported even on a success.