---
title: "Render an MCP App widget headlessly"
method: POST
path: "/projects/{projectId}/servers/{serverId}/widgets/render"
tags: ["Execution"]
---

# Render an MCP App widget headlessly

`POST /projects/{projectId}/servers/{serverId}/widgets/render`

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.

## Path parameters

- `projectId` string, required
- `serverId` string, required

## Request body

- RenderServerWidgetRequest
  - `toolName` string, required — The MCP App tool to render. A tool that declares no `ui://` UI resource is refused (422) rather than run.
  - `parameters` object
  - `includeSnapshot` boolean — 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.
  - `includeScreenshot` boolean — Also return a base64 image. **Default false**: it is by far the largest field this returns.
  - `injectOpenAiCompat` boolean — Mount with the OpenAI Apps compatibility shims instead of the spec-default MCP-UI bridge.
  - `viewport` object
    - `width` integer
    - `height` integer

## Response `200`

The render verdict and its evidence.

- WidgetRenderResult
  - `status` string, required — The render verdict, e.g. `rendered`.
  - `resourceUri` string
  - `bridgeInitialized` boolean
  - `consoleErrors` string[]
  - `blockedRequests` string[] — 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.
  - `snapshot` WidgetSnapshot
    - `mode` 'a11y', required
    - `tree` string, required — Playwright ARIA snapshot of the widget frame.
    - `elements` WidgetSnapshotElement[], required — Interactive elements, in the same role/name/testId vocabulary the interaction steps accept.
      - `role` object
        - `role` string
        - `name` string
      - `testId` string
      - `text` string
      - `ambiguous` boolean — More than one element matched this role and name.
    - `truncated` boolean — The tree hit the character ceiling and was clipped.
    - `capturedAt` integer, required
    - `note` string — Why nothing was captured, when nothing was.
  - `screenshot` object — Present only when `includeScreenshot` was explicitly requested.
    - `mimeType` string
    - `base64` string
  - `timings` object
    - `renderMs` integer
    - `totalMs` integer

## Other responses

- `400` — Malformed body or parameters.
- `401` — Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key.
- `403` — Key is valid but not allowed to do this.
- `404` — Unknown project, server, or resource.
- `422` — The tool declares no MCP App UI resource, or headless Chromium is unavailable on this deployment.
- `429` — Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter.
- `500` — Something failed on MCPJam's side.
- `502` — Could not connect to the target MCP server.
- `504` — The target MCP server connected but didn't respond in time.

---

[API](https://skmtc.net/mcpjam/apis/mcpjam-api.md) · [All operations](https://skmtc.net/mcpjam/apis/mcpjam-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mcpjam/mcpjam-api/revisions/087a1084c020/schema)