Migrate Oai App
Port an OpenAI Apps SDK app that uses window.openai and openai/outputTemplate onto the MCP Apps SDK so it runs in MCP-aware coding agents and chat clients.
Overview
migrate-oai-app is an agent skill for the Build phase that guides converting OpenAI Apps SDK applications to the MCP Apps SDK (@modelcontextprotocol/ext-apps) with API mapping tables and a completion checklist.
Install
npx skills add https://github.com/modelcontextprotocol/ext-apps --skill migrate-oai-appWhat is this skill?
- Step-by-step path from OpenAI Apps SDK to @modelcontextprotocol/ext-apps
- Before/after API mapping tables for window.openai and outputTemplate patterns
- Clone pinned ext-apps repo for reference docs and working examples
- Package-manager-first dependency adds (no guessed version pins)
- Mandatory final todo to re-walk the skill’s Before Finishing checklist
- Pinned ext-apps clone via npm view version tag
- Migration reference guide with before/after API mapping tables
- Explicit Before Finishing checklist at end of workflow
Adoption & trust: 525 installs on skills.sh; 2.4k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a working OpenAI Apps SDK app tied to window.openai and outputTemplate patterns but need it to run as an open MCP App without re-guessing every API equivalent.
Who is it for?
Indie builders migrating an existing OpenAI embedded app or skybridge project into MCP clients they already use for daily coding.
Skip if: Greenfield MCP servers with no OpenAI Apps SDK heritage, or teams that only need conceptual MCP docs without a porting checklist.
When should I use this skill?
User asks to migrate from OpenAI Apps SDK, convert an OpenAI App to MCP, port from window.openai or skybridge, or convert openai/outputTemplate usage.
What do I get? / Deliverables
You finish with dependencies on @modelcontextprotocol/ext-apps, ported call sites aligned to the migration guide, and a verified Before Finishing checklist before marking migration todos done.
- MCP Apps SDK project wired to @modelcontextprotocol/ext-apps
- Completed API remapping per the migration guide
- Before Finishing checklist sign-off on the final migration todo
Recommended Skills
Journey fit
Migration is an integration refactor done while you are wiring agent-facing UI and tools into the product, not during launch SEO or ops monitoring. ext-apps and MCP protocol wiring sit squarely in agent integrations—the same shelf as other MCP servers and embedded app surfaces.
How it compares
Use for a protocol migration playbook with mapping tables—not as a substitute for building net-new MCP tools from scratch.
Common Questions / FAQ
Who is migrate-oai-app for?
Solo and small teams maintaining OpenAI Apps SDK UIs who want one MCP-standard package for agent clients.
When should I use migrate-oai-app?
During Build integrations when you are asked to migrate from OpenAI Apps SDK, convert window.openai usage, port skybridge apps, or move openai/outputTemplate flows to ext-apps.
Is migrate-oai-app safe to install?
Treat it as procedural migration guidance; review the Security Audits panel on this Prism page and inspect cloned repos and npm packages before running install commands in production repos.
SKILL.md
READMESKILL.md - Migrate Oai App
# Migrate OpenAI App to MCP Migrate existing OpenAI Apps SDK applications to the MCP Apps SDK (`@modelcontextprotocol/ext-apps`). The MCP Apps SDK provides a standardized, open protocol for interactive UIs in conversational clients. ## Best Practices - Use your package manager to add dependencies (e.g., `npm install`, `pnpm add`, `yarn add`) instead of manually writing version numbers. This lets the package manager resolve the latest compatible versions. Never specify version numbers from memory. - Preemptively add a final todo item with this exact wording: "Re-read the 'Before Finishing' checklist in this skill and address each checkbox individually, stating what you did for each one, before marking this todo complete." ## Getting Reference Code Clone the SDK repository for complete migration documentation and working examples: ```bash git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps ``` ### Migration Reference Guide Read the migration reference guide with "before/after" mapping tables: `/tmp/mcp-ext-apps/docs/migrate_from_openai_apps.md` ### API Reference (Source Files) Read JSDoc documentation directly from `/tmp/mcp-ext-apps/src/*`: | File | Contents | |------|----------| | `src/app.ts` | `App` class, handlers, lifecycle | | `src/server/index.ts` | `registerAppTool`, `registerAppResource` | | `src/spec.types.ts` | Type definitions | | `src/react/useApp.tsx` | `useApp` hook for React apps | | `src/react/use*.ts*` | Other `use*` hooks for React apps | ### Front-End Framework Examples See `/tmp/mcp-ext-apps/examples/basic-server-{framework}/` for basic SDK usage examples organized by front-end framework: | Template | Key Files | |----------|-----------| | `basic-server-vanillajs/` | `server.ts`, `src/mcp-app.ts`, `mcp-app.html` | | `basic-server-react/` | `server.ts`, `src/mcp-app.tsx` (uses `useApp` hook) | | `basic-server-vue/` | `server.ts`, `src/App.vue` | | `basic-server-svelte/` | `server.ts`, `src/App.svelte` | | `basic-server-preact/` | `server.ts`, `src/mcp-app.tsx` | | `basic-server-solid/` | `server.ts`, `src/mcp-app.tsx` | ## CSP Investigation MCP Apps HTML is served as an MCP resource, not as a web page, and runs in a sandboxed iframe with no same-origin server. **Every** origin must be declared in CSP—including the origin serving your JS/CSS bundles (`localhost` in dev, your CDN in production). Missing origins fail silently. **Before writing any migration code**, build the app and investigate all origins it references: 1. Build the app using the existing build command 2. Search the resulting HTML, CSS, and JS for **every** origin (not just "external" origins—every network request will need CSP approval) 3. For each origin found, trace back to source: - If it comes from a constant → universal (same in dev and prod) - If it comes from an env var or conditional → note the mechanism and identify both dev and prod values 4. Check for third-party libraries that may make their own requests (analytics, error tracking, etc.) **Document your findings** as three lists, and note for each origin whether it's universal, dev-only, or prod-only: - **resourceDomains**: origins serving images, fonts, styles, scripts - **connectDomains**: origins for API/fetch requests - **frameDomains**: origins for nested iframes If no origins are found, the app may not need custom CSP domains. ## CORS Configuration MCP clients make cross-origin requests. If using Express, `app.use(cors())` handles this. For raw HTTP servers, configure s