> ## Documentation Index
> Fetch the complete documentation index at: https://toolgrain.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Compatibility and acceptance

> Verify hosts and diagnose widget connection problems.

MCP Apps compatibility is host-version and transport specific. Protocol tests do not establish real host rendering compatibility.

| Flow | Status |
| - | - |
| Native browser/React lifecycle | Covered by automated fixtures |
| React host actions | Capability/modalities, requests/results, deadlines, cancellation, and cleanup covered by fixtures; no live-host acceptance yet |
| Separate/shared HTML resources | Covered by the Bun/Elysia example checks |
| Core revisions and fallback results | Covered by server/transport tests |
| Claude Desktop 4.23118.0, macOS 26.5.2, local stdio | Separate/shared Weather and Sales rendering, metadata, refresh calls, and light/dark updates passed on 2026-11-06 |
| Official Apps SDK 2.0.4 widget against Toolgrain | Passed with a self-authored DOM host fixture and direct MCP 2026-07-28 dispatch; not a live-host rendering claim |

## Stable publication verification

On November 8, 2026, [Release PR #63](https://github.com/keshavkatwe/toolgrain/pull/63)
merged as [`d067bbb`](https://github.com/keshavkatwe/toolgrain/commit/d067bbb8d1710b232d026d1f3754c9b0fd112d4f). The
[release run](https://github.com/keshavkatwe/toolgrain/actions/runs/42451243089)
published 0.3.0 for all seven libraries under npm's `latest` tag after the full
release matrix passed. Downloaded archives matched the verified build artifacts;
both npm metadata formats, registry integrity, and fresh npm/Node 24.20.0 and
Bun 1.4.4 consumers passed. All seven versions include npm provenance.

These checks verify published packages, declarations, and protocol flows. The
live Claude Desktop record below retains its original version, date, and local
stdio scope. Host actions and live HTTP widgets have no additional live-host
acceptance from this publication run.

## Published alpha verification

The [November 6, 2026 publication run](https://github.com/keshavkatwe/toolgrain/actions/runs/42244638853) completed `0.3.0-alpha.2` for all seven Toolgrain libraries. Registry checks matched the actual downloaded archives to the verified artifacts in both npm metadata formats. Fresh npm/Node 24.20.0 and Bun 1.4.4 consumers passed imports, minimum/current declarations, and stdio/HTTP flows.

These publication checks are separate from the live Claude Desktop test below, which exercised the Apps implementation before the combined alpha publication. Published `0.3.0-alpha.3` adds named wire types and host actions; live-host acceptance for the new actions remains pending. Neither result establishes untested host versions or transports.

## Alpha.3 publication verification

The [November 7, 2026 publication run](https://github.com/keshavkatwe/toolgrain/actions/runs/42393275595) completed `0.3.0-alpha.3` for all seven libraries from commit `9d9c3a2fef842d60beb229943c0bf0b6704cf835`. All seven downloaded npm archives matched the approved build; both npm metadata formats, existing `latest` tags, and fresh Node/Bun consumers passed verification. React's first CI/OIDC publication includes provenance identifying that source commit.

This verifies package publication and automated consumers. The new host actions still have fixture coverage rather than live Claude Desktop acceptance.

## Vite walkthrough verification

On November 7, 2026, the [Vite walkthrough](https://toolgrain.mintlify.site/mcp-apps/quickstart.md) was checked from a fresh `create-vite@9.3.4` React/TypeScript scaffold using published `0.3.0-alpha.3`, Node 24.22.2, Vite 8.3.4, and `vite-plugin-singlefile` 2.3.4. The initial widget, refresh component, typed resource/result metadata, and separate weather/sales builds compiled. Each output HTML contained its own JavaScript/CSS; real stdio tool calls and resource reads passed under both supported outer MCP revisions, including assistant fallback content.

These are local build/compiler and protocol checks. The exact scaffold was not tested in a live Claude Desktop session; the separately recorded host test below retains its original scope.

On November 8, 2026, the weather quickstart was rechecked from a fresh scaffold
with published Toolgrain 0.3.0, Node 24.22.2, React 19.3.1, Vite 8.3.4, and
`vite-plugin-singlefile` 2.3.4. The documented files compiled into a single HTML
widget. Tool calls, assistant fallback text, resource listing/reading, the Apps
MIME type, and resource metadata passed over real stdio in both supported MCP
revisions. This check did not add live-host rendering coverage.

## Claude Desktop acceptance

The recorded local test used Bun 1.4.4 to launch the built example's stdio entry. Claude advertised `io.modelcontextprotocol/ui` with the Apps HTML MIME type and negotiated outer MCP `2025-06-18`; the iframe negotiated Apps `2026-01-26`. Both separate entries and both metadata-routed shared entries displayed their expected data. City and region buttons updated each widget through host-mediated tool calls, and existing widgets followed light/dark host theme changes. The temporary connector and appearance changes were removed after testing.

This verifies only that host version and local stdio configuration. Claude HTTP connections, host-driven cancellation, and host permission/CSP enforcement were not exercised live. Cancellation, errors, malformed traffic, lifecycle cleanup, and fallback envelopes are covered by automated fixtures; these checks do not establish host policy behavior.

Build the example, then configure a local stdio connection launching its `start:stdio` command with a supported Bun runtime. Record the exact Claude Desktop version, OS, negotiated outer revision, Apps capabilities, and connection configuration without credentials or local machine paths.

Call each separate tool and both shared tools. Confirm the expected widget, initial structured and metadata data, city/region buttons, host theme changes, expected errors, cancellation, and normal text fallback. Disconnect and confirm cleanup.

For the new host actions, additionally record the host's action/content-kind advertisements and display modes. Test link opening, an explicit user message, replacement context on a later turn, and both requested/actual modes. Confirm unsupported controls and declined actions behave usefully. The recorded test above did not exercise these additions.

For HTTP testing, configure the application's allowed hosts explicitly. Using a public connector or tunnel is a separate exposure/deployment decision; the example does not open one automatically.

## Interoperability acceptance

Run `bun run test:interop` from the repository root. It builds an independently authored widget with pinned official SDK dependencies in a disposable installation outside the workspace. The fixture checks resource/security metadata, initialization, structured content/result metadata, a host-mediated call, and a theme update. Its report stays ignored under `reports/`.

Use an independently built widget using the official Apps SDK, served by a Toolgrain resource and tool. Verify initial results, host-mediated tool calls, and security metadata. Keep SDK dependencies confined to that external acceptance fixture, outside Toolgrain's runtime packages.

## Troubleshooting

A connection timeout usually means the page was opened without an Apps host, the host does not support Apps, or its iframe handshake did not complete. Verify the resource MIME type and tool URI. A routing error means a shared entry could not select a tool; inspect its application-owned marker. An unsupported tool-call error means the host did not advertise serverTools. Inspect errors and preserve useful assistant content for all cases.

Claude Desktop cached resource HTML for a connector instance during the recorded test. Restarting the temporary connector was needed to test changed HTML; starting a new chat alone did not reload it. Recheck this behavior when testing another host version.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.