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.
Fetches migrate-oai-app from modelcontextprotocol/ext-apps and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/migrate-oai-app
Restart Cursor to activate migrate-oai-app. Access via /migrate-oai-app in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
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:
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:
Build the app using the existing build command
Search the resulting HTML, CSS, and JS for every origin (not just "external" origins—every network request will need CSP approval)
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
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:
Use registerAppTool() and registerAppResource() helpers instead of raw server.registerTool() / server.registerResource(). These helpers handle the MCP Apps metadata format automatically.
See /tmp/mcp-ext-apps/docs/migrate_from_openai_apps.md for server-side mapping tables.
Client-Side
The fundamental paradigm shift: OpenAI uses a synchronous global object (window.openai.toolInput, window.openai.theme) that's pre-populated before your code runs. MCP Apps uses an App instance with async event handlers.
Key differences:
Create an App instance and register handlers (ontoolinput, ontoolresult, onhostcontextchanged) before calling connect(). (Events may fire immediately after connection, so handlers must be registered first.)
Access tool data via handlers: app.ontoolinput for window.openai.toolInput, app.ontoolresult for window.openai.toolOutput.
Access host environment (theme, locale, etc.) via app.getHostContext().
For React apps, the useApp hook manages this lifecycle automatically—see basic-server-react/ for the pattern.
See /tmp/mcp-ext-apps/docs/migrate_from_openai_apps.md for client-side mapping tables.
Features Not Yet Available in MCP Apps
These OpenAI features don't have MCP equivalents yet:
Search for and migrate any remaining client-side OpenAI patterns:
Pattern
Indicates
window.openai.toolInput
Old global → params.arguments in ontoolinput handler
window.openai.toolOutput
Old global → params.structuredContent in ontoolresult
window.openai
Old global API → App instance methods
For each origin from your CSP investigation, show where it appears in the registerAppResource() CSP config. Every origin from the CSP investigation (universal, dev-only, prod-only) must be included in the CSP config—MCP Apps HTML runs in a sandboxed iframe with no same-origin server. If an origin was not included in the CSP config, add it now.
For each conditional (dev-only, prod-only) origin from your CSP investigation, show the code where the same configuration setting (env var, config file, etc.) controls both the runtime URL and the CSP entry. If the CSP has a hardcoded origin that should be conditional, fix it now—the app must be production-ready.
Testing
Using basic-host
Test the migrated app with the basic-host example:
# Terminal 1: Build and run your servernpm run build &&npm run serve
# Terminal 2: Run basic-host (from cloned repo)cd /tmp/mcp-ext-apps/examples/basic-host
npminstallSERVERS='["http://localhost:3001/mcp"]'npm run start
# Open http://localhost:8080
Verify Runtime Behavior
Once the app loads in basic-host, confirm:
App loads without console errors
ontoolinput handler fires with tool arguments
ontoolresult handler fires with tool result
Implementation Guide
Prerequisites
›Claude Desktop or compatible AI client with skill support
›Clear understanding of task or problem to solve
›Willingness to iterate and refine outputs
Time Estimate
15-45 minutes depending on use case complexity
Steps
1Install skill using provided installation command
2Test with simple use case relevant to your work
3Evaluate output quality and relevance
4Iterate on prompts to improve results
5Integrate into regular workflow if valuable
Common Pitfalls
⚠Expecting perfect results without iteration
⚠Not providing enough context in prompts
⚠Using skill for tasks outside its intended scope
⚠Accepting outputs without review and validation
Best Practices
✓ Do
+Start with clear, specific prompts
+Provide relevant context and constraints
+Review and refine all outputs before using
+Iterate to improve output quality
+Document successful prompt patterns
✗ Don't
−Don't use without understanding skill limitations
−Don't skip validation of outputs
−Don't share sensitive information in prompts
−Don't expect skill to replace human judgment
💡 Pro Tips
★Be specific about desired format and style
★Ask for multiple options to choose from
★Request explanations to understand reasoning
★Combine AI efficiency with human expertise
When to Use This
✓ Use when
Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.
✗ Avoid when
Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.
Learning Path
1Familiarize yourself with skill capabilities and limitations
2Start with low-risk, non-critical tasks
3Progress to more complex and valuable use cases
4Build expertise through regular use and experimentation
