MCP Apps SDK Common questions about building MCP Apps with the MCP Apps SDK (Documentation Index
Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
@modelcontextprotocol/ext-apps). For the conceptual overview, start with What are MCP Apps?.
What is an MCP App?
What is an MCP App?
An MCP App is an interactive UI that an MCP server delivers and an AI chat host renders inside the conversation. MCP Apps is an extension to the Model Context Protocol that defines how a server declares UI resources, how a host renders them in a sandboxed iframe, and how the UI and host communicate. A tool returns its data as usual; the host pairs that data with the app’s HTML to show a chart, form, map, or any other interface. See the introduction.
How is an MCP App different from a regular MCP tool?
How is an MCP App different from a regular MCP tool?
A regular tool returns text and structured data that the model reads. An MCP App links a tool to an HTML UI resource, so when the tool runs the host renders that UI and passes it the tool result. The tool still returns text for the model, so the same tool works whether or not the host can render UI. See register an app tool.
Which AI hosts support MCP Apps?
Which AI hosts support MCP Apps?
ChatGPT and Claude render MCP Apps today. The protocol is host-agnostic, so other hosts can adopt it without changes to your server. Hosts advertise their UI support when they connect, and your server checks those capabilities before registering UI-enabled tools. See capability detection.
What happens if a host doesn't support MCP Apps?
What happens if a host doesn't support MCP Apps?
Tools still work. MCP Apps is built for graceful degradation: a host that can’t render UI receives the tool’s text and structured content as normal, and never sees the UI resource. Because your server checks host capabilities at connection time, you can register the same tools everywhere and let UI-capable hosts render the app. See capability detection.
How does a server deliver a UI to the host?
How does a server deliver a UI to the host?
The server declares UI resources as HTML templates under the
ui:// URI scheme with the text/html;profile=mcp-app MIME type, then links a tool to its template through resource metadata. Declaring templates upfront lets hosts prefetch and cache them, keeps presentation separate from data, and lets hosts review the UI during connection setup. See MCP resources and resource metadata.How does the UI communicate with the host?
How does the UI communicate with the host?
The app runs in a sandboxed iframe and exchanges JSON-RPC messages with the host over
postMessage. From the app you can call server tools, send messages to the thread, update model context, request a display mode, open links, and more. The full set lives in the Requests API, and the connection sequence is covered in the lifecycle.Can an MCP App fetch fresh data or trigger server actions?
Can an MCP App fetch fresh data or trigger server actions?
Yes. Call back into your server’s tools from the app with
callServerTool. This is how a refresh button reloads data, a form submits, or a control paginates without leaving the conversation. Tools can also be marked app-only (visibility: ["app"]) so the model never sees interaction-only tools. See tool visibility and app tools.Can an MCP App make network requests to my own API?
Can an MCP App make network requests to my own API?
Only to the domains your server declares. The server lists allowed network domains in the resource’s CSP metadata, and the host enforces them. If no domains are declared, the app makes no external connections. See CSP and CORS.
What display modes can an MCP App use?
What display modes can an MCP App use?
Three:
inline (embedded in the chat flow), fullscreen (takes over the window), and pip (a picture-in-picture overlay). The app declares which modes it supports and the host declares which it can provide; the host has final say. Switch modes from the app with requestDisplayMode.How does an MCP App match the host's light or dark theme?
How does an MCP App match the host's light or dark theme?
The host injects its theme as CSS variables and reports the current theme in the host context, updating it through
onhostcontextchanged. Style your app with the host’s CSS variables so it follows the host’s colors, fonts, and spacing automatically. See theming.What language or framework do I build an MCP App in?
What language or framework do I build an MCP App in?
The app is plain HTML and JavaScript running in an iframe, so any frontend stack works. The MCP Apps SDK ships TypeScript helpers and React hooks for the host connection (see the App class and React hooks). The sunpeak framework layers a React-first, convention-over-configuration project structure on top.
How do I test an MCP App without deploying to a host?
How do I test an MCP App without deploying to a host?
Run it in the inspector, a local replica of the ChatGPT and Claude runtimes.
sunpeak inspect --server <url> works against any MCP server in any language, and sunpeak dev adds hot reload for sunpeak projects. You can also automate the loop with e2e, visual regression, eval, and live tests. See the testing overview.How are MCP Apps kept secure?
How are MCP Apps kept secure?
Apps run in sandboxed iframes with no access to the host’s DOM, cookies, or storage, and all communication flows through
postMessage, which makes it auditable. Network access is limited to the domains the server declares through CSP metadata, enforced by the host. See CSP and CORS.