Pattern to reuse iframe-embed as an MCP App

[ochafik]

Lots of people might come to MCP Apps w/ an existing iframe embed, not wanting to reimplement everything.

But some hosts might balk at allowing nested external iframes (which can't be audited easily).

Here is a rough suggestion on how to turn an iframe embed app (supposedly taking its parameters from the URL query params) into an MCP App (which just takes its parameters from the tool outputs, or inputs).

Taking the following embed.ts (normally iframed as https://myhost.com/embed.html?q=some+search), we can have initialization logic that fetches params from the MCP App's tool results instead of from its query params, if we're not iframed.

(Jan 27th 2026: edited to match 1.x APIs)

import { App } from "@modelcontextprotocol/ext-apps";

const isMcpApp = () => window.location.host !== 'myhost.com';

// Returns the query params when embedded, or the MCP tool result' structuredContent
async function getParameters(): Promise<Record<string, string>> {
 if (isMcpApp()) {
 const app = new McpApp({name: 'Our App', version: ''});
 await app.connect();
 return new Promise(resolve => {
 app.ontoolresult = ({structuredContent}) => resolve(structuredContent);
 // Note: inputs are available too.
 });
 } else {
 return Object.fromEntries([...new URL(window.location.href).searchParams])
 }
}

async function main() {
 const {q: query} = await getParameters();
 ...
}
main().catch(...)

import { registerAppTool, registerAppResource } from "@modelcontextprotocol/ext-apps/server";
import { McpServer } from "@modelcontextprotocol/sdk/...";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/...";

const server = new McpServer({name: 'Example Server', version: '1.0.0'});

const uiHtml = await fetch("dist/embed.html").then(r => t.text());
const resourceUri = 'ui://example';

registerAppResource(server, {
 uri: resourceUri,
 ....,
 content: uiHtml,
 _meta: {
 ui: {
 csp: {
 connectDomains: ['api.myhost.com']
 }
 }
 }
})
registerAppTool(server, 'show-embed', {
 inputSchema: z.object({q: z.string()}).shape,
 _meta: {
 ui: { resourceUri }
 }
}, ({message}) => {
 return {
 content: [],
 structuredContent: {q: 'the query'`}
 }
})
 
server.server.connect(new StdioServerTransport())
.then(() => console.error('Server is running');

[liady]

@ochafik good points. It resembles Next.js's method for automatically "converting" all their apps to Apps SDK:

• fetch in the MCP server - https://github.com/vercel-labs/chatgpt-apps-sdk-nextjs-starter/blob/main/app/mcp/route.ts#L32
• custom logic for the code itself - https://github.com/vercel-labs/chatgpt-apps-sdk-nextjs-starter/blob/main/app/layout.tsx#L40

It also makes me think we need a way to signal the UI that it's running in an MCP Apps environment. In Apps SDK there's a window.openai to detect, but currently in the SEP we're not proposing any UI SDK. We can also defer it to the servers themselves to "inject" custom code to the returned HTML so it would behave differently, but that's probably a point we need to consider.

[idosal]

Completely agree. Existing apps have always been the easiest path to adoption (although in some cases, a rewrite is the better path forward).
This feature is effectively the same as converting externalUrl to rawHtml. It's implemented in the last part of the MCP-UI<>MCP Apps server adapter layer (I'll push the remaining commits tomorrow night).