NuxtMCP Toolkit
Apps

Testing & publishing

Test MCP Apps locally, pick a compatible host, and ship HTTPS endpoints for ChatGPT, Claude, and IDE clients.

Host compatibility

HostRendersendPromptcallToolopenLinkNotes
Cursor✅✅✅✅Tested with the JSON-RPC bridge and legacy ready/resize messages.
ChatGPT (Apps SDK)✅⚠️✅✅Uses window.openai when available. Follow-ups are sent, but the next tool is not always rendered inline.
MCP UI / Inspector-style hosts✅variesvariesvariesThe bridge emits spec JSON-RPC messages plus legacy mcp-ui envelopes where useful. Verify each host before documenting support.

The bridge auto-detects the host on handshake and adapts to its protocol — modern JSON-RPC for MCP UI hosts, the legacy mcp-ui envelope for older clients, the ChatGPT Apps SDK globals when present. Your code just calls useMcpApp().

Test locally

  1. Start Nuxt (pnpm dev / nuxt dev). The MCP server uses the same route as tools — default /mcp unless you set mcp.route in nuxt.config.
  2. List tools and invoke the app with the MCP Inspector or the MCP panel in Nuxt DevTools. You should see a tool named after the SFC (e.g. color-picker). The tool return includes a text/html;profile=mcp-app resource; the client must support MCP UI to show the iframe (some clients only show text fallbacks).
  3. Point a desktop / IDE client at the same URL as for normal MCP usage:
    • add-mcp: npx add-mcp http://localhost:3000/mcp
    • Or configure Cursor, Claude Code, VS Code, or Claude Desktop manually — see Connect your IDE.
  4. Exercise the UI bridge in a host that implements MCP Apps: from your iframe, use callTool, sendPrompt, and openLink and confirm behaviour against the compatibility table above.
  5. Iterate on csp.resourceDomains / csp.connectDomains if images or fetch calls are blocked; watch the browser console inside the host’s devtools for CSP violations.

Publish for end users (HTTPS)

MCP Apps do not use a second URL. They are tools registered on the same streamable HTTP MCP server as the rest of your surface.

  • Deploy Nuxt (or your Node host) with a public HTTPS origin. Document a single base URL, e.g. https://your-product.com/mcp (or your mcp.route).
  • Give users a copy-paste add-mcp one-liner and/or InstallButton — see Share your MCP with users (production).
  • If the endpoint is authenticated, document required headers (e.g. Authorization) next to the URL; the same rules apply to tools and apps.

Claude, Cursor, and coding agents

  • Claude Code, Claude Desktop (where remote MCP is enabled), Cursor, VS Code, and Codex-style clients connect to your server with the same MCP URL you use for tools. There is no separate “apps-only” endpoint.
  • Web and mobile ChatGPT/Claude apps may or may not render MCP UI widgets on a given build — always verify inline iframes on the product version you support.
  • Prefer Cursor as the main dev vehicle when debugging the JSON-RPC UI bridge; it is the most exercised environment in this module’s test suite.

ChatGPT and OpenAI

  • When the host exposes the Apps SDK (window.openai) or enforces widget CSP, the toolkit mirrors your csp to _meta.ui.csp and openai/widgetCSP. Behaviour (especially sendPrompt and follow-up re-renders) can change between releases — re-check the compatibility table when you upgrade.
  • OAuth, org policies, and connector setup for ChatGPT / OpenAI products are documented on OpenAI’s platform; they are outside this module.

Related

CSP & build pipeline

Content Security Policy, allow-listed domains, and how HTML bundles are produced.

Patterns & limits

UI patterns, unsupported Nuxt features in the iframe, and API reference.

Copyright © 2026