openai-apps-mcp（OpenAI apps MCP 问题管理） Skills下载安装命令和教程

安装方式

通过对话安装

复制提示词发给支持本地命令或 Skills 的 AI 助手，先确认命令和权限，再让它执行。

请帮我安装这个 Agent Skill：openai-apps-mcp（OpenAI apps MCP 问题管理）
来源仓库：https://github.com/jezweb/claude-skills
仓库路径：skills/openai-apps-mcp
安装命令：
npx skills add https://github.com/jezweb/claude-skills --skill 'OpenAI Apps MCP'
安装前请先检查当前环境是否支持对应 CLI，并向我确认将要执行的命令、安装目录、联网范围和文件读写权限；确认后再执行。

命令行安装

复制命令到本机终端执行。不同来源提供的安装方式可能略有差异；本站展示可直接复制的安装命令，安装前请核对来源页面。

skills.shnpx skills

npx skills add https://github.com/jezweb/claude-skills --skill 'OpenAI Apps MCP'

简介

在 Cloudflare Workers 上使用 MCP 服务器构建 ChatGPT 应用程序，使用自定义工具和交互式 HTML/JS 小部件扩展 ChatGPT。

实现 JSON-RPC 2.0 MCP 协议，通过 ASSETS 绑定进行工具注册、执行和小部件资源服务
https://chatgpt.com 需要 CORS 许可名单, ui://小部件/
小部件的 URI 前缀，以及 text/html+skybridge
MIME类型
防止 14 个已记录的问题，包括 CORS 块、小部件 404、MIME 类型配置错误、SSE 超时和 Next.js 集成冲突（在 SDK v1.25.3+ 中已修复）
通过 _meta.initialData 支持小部件状态，工具发起的调用 widgetCallable: true
flag，以及200ms响应目标下的性能优化

SKILL.md

Building OpenAI Apps with Stateless MCP Servers

Status: Production Ready Last Updated: 2026-01-21 Dependencies: cloudflare-worker-base, hono-routing (optional) Latest Versions: @modelcontextprotocol/sdk@1.25.3, hono@4.11.3, zod@4.3.5, wrangler@4.58.0

Overview

Build ChatGPT Apps using MCP (Model Context Protocol) servers on Cloudflare Workers. Extends ChatGPT with custom tools and interactive widgets (HTML/JS UI rendered in iframe).

Architecture: ChatGPT → MCP endpoint (JSON-RPC 2.0) → Tool handlers → Widget resources (HTML)

Status: Apps available to Business/Enterprise/Edu (GA Nov 13, 2025). MCP Apps Extension (SEP-1865) formalized Nov 21, 2025.

Quick Start

1. Scaffold & Install

npm create cloudflare@latest my-openai-app -- --type hello-world --ts --git --deploy false
cd my-openai-app
npm install @modelcontextprotocol/sdk@1.25.3 hono@4.11.3 zod@4.3.5
npm install -D @cloudflare/vite-plugin@1.17.1 vite@7.2.4

2. Configure wrangler.jsonc

{
  "name": "my-openai-app",
  "main": "dist/index.js",
  "compatibility_flags": ["nodejs_compat"],  // Required for MCP SDK
  "assets": {
    "directory": "dist/client",
    "binding": "ASSETS"  // Must match TypeScript
  }
}

3. Create MCP Server (`src/index.ts`)

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const app = new Hono<{ Bindings: { ASSETS: Fetcher } }>();

// CRITICAL: Must allow chatgpt.com
app.use('/mcp/*', cors({ origin: 'https://chatgpt.com' }));

const mcpServer = new Server(
  { name: 'my-app', version: '1.0.0' },
  { capabilities: { tools: {}, resources: {} } }
);

// Tool registration
mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'hello',
    description: 'Use this when user wants to see a greeting',
    inputSchema: {
      type: 'object',
      properties: { name: { type: 'string' } },
      required: ['name']
    },
    annotations: {
      openai: { outputTemplate: 'ui://widget/hello.html' }  // Widget URI
    }
  }]
}));

// Tool execution
mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'hello') {
    const { name } = request.params.arguments as { name: string };
    return {
      content: [{ type: 'text', text: `Hello, ${name}!` }],
      _meta: { initialData: { name } }  // Passed to widget
    };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

app.post('/mcp', async (c) => {
  const body = await c.req.json();
  const response = await mcpServer.handleRequest(body);
  return c.json(response);
});

app.get('/widgets/*', async (c) => c.env.ASSETS.fetch(c.req.raw));

export default app;

4. Create Widget (`src/widgets/hello.html`)

<!DOCTYPE html>
<html>
<head>
  <style>
    body { margin: 0; padding: 20px; font-family: system-ui; }
  </style>
</head>
<body>
  <div id="greeting">Loading...</div>
  <script>
    if (window.openai && window.openai.getInitialData) {
      const data = window.openai.getInitialData();
      document.getElementById('greeting').textContent = `Hello, ${data.name}! 👋`;
    }
  </script>
</body>
</html>

5. Deploy

npm run build
npx wrangler deploy
npx @modelcontextprotocol/inspector https://my-app.workers.dev/mcp

Critical Requirements

CORS: Must allow https://chatgpt.com on /mcp/* routes Widget URI: Must use ui://widget/ prefix (e.g., ui://widget/map.html) MIME Type: Must be text/html+skybridge for HTML resources Widget Data: Pass via _meta.initialData (accessed via window.openai.getInitialData()) Tool Descriptions: Action-oriented ("Use this when user wants to...") ASSETS Binding: Serve widgets from ASSETS, not bundled in worker code SSE: Send heartbeat every 30s (100s timeout on Workers)

Known Issues Prevention

This skill prevents 14 documented issues:

Issue #1: CORS Policy Blocks MCP Endpoint

Error: Access to fetch blocked by CORS policy Fix: app.use('/mcp/*', cors({origin: 'https://chatgpt.com'}))

Issue #2: Widget Returns 404 Not Found

Error: 404 (Not Found) for widget URL Fix: Use ui://widget/ prefix (not resource:// or /widgets/)

annotations: { openai: { outputTemplate: 'ui://widget/map.html' } }

Issue #3: Widget Displays as Plain Text

Error: HTML source code visible instead of rendered widget Fix: MIME type must be text/html+skybridge (not text/html)

server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [{ uri: 'ui://widget/map.html', mimeType: 'text/html+skybridge' }]
}));

Issue #4: ASSETS Binding Undefined

Error: TypeError: Cannot read property 'fetch' of undefined Fix: Binding name in wrangler.jsonc must match TypeScript

{ "assets": { "binding": "ASSETS" } }  // wrangler.jsonc

type Bindings = { ASSETS: Fetcher };  // index.ts

Issue #5: SSE Connection Drops After 100 Seconds

Error: SSE stream closes unexpectedly Fix: Send heartbeat every 30s (Workers timeout at 100s inactivity)

const heartbeat = setInterval(async () => {
  await stream.writeSSE({ data: JSON.stringify({ type: 'heartbeat' }), event: 'ping' });
}, 30000);

Issue #6: ChatGPT Doesn't Suggest Tool

Error: Tool registered but never appears in suggestions Fix: Use action-oriented descriptions

// ✅ Good: 'Use this when user wants to see a location on a map'
// ❌ Bad: 'Shows a map'

Issue #7: Widget Can't Access Initial Data

Error: window.openai.getInitialData() returns undefined Fix: Pass data via _meta.initialData

return {
  content: [{ type: 'text', text: 'Here is your map' }],
  _meta: { initialData: { location: 'SF', zoom: 12 } }
};

Issue #8: Widget Scripts Blocked by CSP

Error: Refused to load script (CSP directive) Fix: Use inline scripts or same-origin scripts. Third-party CDNs blocked.

<!-- ✅ Works --> <script>console.log('ok');</script>
<!-- ❌ Blocked --> <script src="https://cdn.example.com/lib.js"></script>

Issue #9: Hono Global Response Override Breaks Next.js (v1.25.0-1.25.2)

Error: No response is returned from route handler (Next.js App Router) Source: GitHub Issue #1369 Affected Versions: v1.25.0 to v1.25.2 Fixed In: v1.25.3 Why It Happens: Hono (MCP SDK dependency) overwrites global.Response, breaking frameworks that extend it (Next.js, Remix, SvelteKit). NextResponse instanceof check fails. Prevention:

Upgrade to v1.25.3+ (recommended)
Before fix: Use webStandardStreamableHTTPServerTransport instead
Or: Run MCP server on separate port from Next.js/Remix/SvelteKit app

// ✅ v1.25.3+ - Fixed
const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
});

// ✅ v1.25.0-1.25.2 - Workaround
import { webStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/index.js';
const transport = webStandardStreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
});

Issue #10: Elicitation (User Input) Fails on Cloudflare Workers

Error: EvalError: Code generation from strings disallowed Source: GitHub Issue #689 Why It Happens: Internal AJV v6 validator uses prohibited APIs on edge platforms Prevention: Avoid elicitInput() on edge platforms (Cloudflare Workers, Vercel Edge, Deno Deploy)

Workaround:

// ❌ Don't use on Cloudflare Workers
const userInput = await server.elicitInput({
  prompt: "What is your name?",
  schema: { type: "string" }
});

// ✅ Use tool parameters instead
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name } = request.params.arguments as { name: string };
  // User provides via tool call, not elicitation
});

Status: Requires MCP SDK v2 to fix properly. Track PR #844.

Issue #11: SSE Transport Statefulness Breaks Serverless Deployments

Error: 400: No transport found for sessionId Source: GitHub Issue #273 Why It Happens: SSEServerTransport relies on in-memory session storage. In serverless environments (AWS Lambda, Cloudflare Workers), the initial GET /sse request may be handled by Instance A, but subsequent POST /messages requests land on Instance B, which lacks the in-memory state. Prevention: Use Streamable HTTP transport (added in v1.24.0) instead of SSE for serverless deployments Solution: For stateful SSE, deploy to non-serverless environments (VPS, long-running containers)

Official Status: Fixed by introducing Streamable HTTP (v1.24+) - now the recommended standard for serverless.

Issue #12: OAuth Configuration Requires TWO Separate Apps

Source: Cloudflare Remote MCP Server Docs Why It Happens: OAuth providers validate redirect URLs strictly. Localhost and production have different URLs, so they need separate OAuth client registrations. Prevention:

# Development OAuth App
Callback URL: http://localhost:8788/callback

# Production OAuth App
Callback URL: https://my-mcp-server.workers.dev/callback

Additional Requirements:

KV namespace for auth state storage (create manually)
COOKIE_ENCRYPTION_KEY env var: openssl rand -hex 32
Client restart required after config changes

Issue #13: Widget State Over 4k Tokens Causes Performance Issues (Community-sourced)

Source: OpenAI Apps SDK - ChatGPT UI Why It Happens: Widget state persists only to a single widget instance tied to one conversation message. State is reset when users submit via the main chat composer instead of widget controls. Prevention: Keep state payloads under 4k tokens for optimal performance

// ✅ Good - Lightweight state
window.openai.setWidgetState({ selectedId: "item-123", view: "grid" });

// ❌ Bad - Will cause performance issues
window.openai.setWidgetState({
  items: largeArray,           // Don't store full datasets
  history: conversationLog,    // Don't store conversation history
  cache: expensiveComputation  // Don't cache large results
});

Best Practice:

Store only UI state (selected items, view mode, filters)
Fetch data from MCP server on widget mount
Use tool calls to persist important data

Issue #14: Widget-Initiated Tool Calls Fail Without Permission Flag (Community-sourced)

Source: OpenAI Apps SDK - ChatGPT UI Why It Happens: Components initiating tool calls via window.openai.callTool() require the tool marked as "able to be initiated by the component" on the MCP server. Without this flag, calls fail silently. Prevention: Mark tools as widgetCallable: true in annotations

// MCP Server - Mark tool as widget-callable
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: 'update_item',
    description: 'Update an item',
    inputSchema: { /* ... */ },
    annotations: {
      openai: {
        outputTemplate: 'ui://widget/item.html',
        // ✅ Required for widget-initiated calls
        widgetCallable: true
      }
    }
  }]
}));

// Widget - Now allowed to call tool
window.openai.callTool({
  name: 'update_item',
  arguments: { id: itemId, status: 'completed' }
});

Widget Development Best Practices

File Upload Limitations (Community-sourced)

Source: OpenAI Apps SDK - ChatGPT UI

window.openai.uploadFile() only supports 3 image formats: image/png, image/jpeg, and image/webp. Other formats fail silently.

// ✅ Supported
window.openai.uploadFile({ accept: 'image/png,image/jpeg,image/webp' });

// ❌ Not supported (fails silently)
window.openai.uploadFile({ accept: 'application/pdf' });
window.openai.uploadFile({ accept: 'text/csv' });

Alternative for Other File Types:

Use base64 encoding in tool arguments
Request user paste text content
Use external upload service (S3, R2) and pass URL

Tool Performance Targets (Community-sourced)

Source: OpenAI Apps SDK - Troubleshooting

Tool calls exceeding "a few hundred milliseconds" cause UI sluggishness in ChatGPT. Official docs recommend profiling backends and implementing caching for slow operations.

Performance Targets:

< 200ms: Ideal response time
200-500ms: Acceptable but noticeable
> 500ms: Sluggish, needs optimization

Optimization Strategies:

// 1. Cache expensive computations
const cache = new Map();
if (cache.has(key)) return cache.get(key);
const result = await expensiveOperation();
cache.set(key, result);

// 2. Use KV/D1 for pre-computed data
const cached = await env.KV.get(`result:${id}`);
if (cached) return JSON.parse(cached);

// 3. Paginate large datasets
return {
  content: [{ type: 'text', text: 'First 20 results...' }],
  _meta: { hasMore: true, nextPage: 2 }
};

// 4. Move slow work to async tasks
// Return immediately, update via follow-up

MCP SDK 1.25.x Updates (December 2025)

Breaking Changes from @modelcontextprotocol/sdk@1.24.x → 1.25.x:

Removed loose type exports (Prompts, Resources, Roots, Sampling, Tools) - use specific schemas
ES2020 target required (previous: ES2018)
setRequestHandler is now typesafe - incorrect schemas throw type errors

New Features:

Tasks (v1.24.0+): Long-running operations with progress tracking
Sampling with Tools (v1.24.0+): Tools can request model sampling
OAuth Client Credentials (M2M): Machine-to-machine authentication

Migration: If using loose type imports, update to specific schema imports:

// ❌ Old (removed in 1.25.0)
import { Tools } from '@modelcontextprotocol/sdk/types.js';

// ✅ New (1.25.1+)
import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';

Zod 4.0 Migration Notes (MAJOR UPDATE - July 2025)

Breaking Changes from zod@3.x → 4.x:

.default() now expects input type (not output type). Use .prefault() for old behavior.
ZodError: error.issues (not error.errors)
.merge() and .superRefine() deprecated
Optional properties with defaults now always apply

Performance: 14x faster string parsing, 7x faster arrays, 6.5x faster objects

Migration: Update validation code:

// Zod 4.x
try {
  const validated = schema.parse(data);
} catch (error) {
  if (error instanceof z.ZodError) {
    return { content: [{ type: 'text', text: error.issues.map(e => e.message).join(', ') }] };
  }
}

Dependencies

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.25.3",
    "hono": "^4.11.3",
    "zod": "^4.3.5"
  },
  "devDependencies": {
    "@cloudflare/vite-plugin": "^1.17.1",
    "@cloudflare/workers-types": "^4.20260103.0",
    "vite": "^7.2.4",
    "wrangler": "^4.54.0"
  }
}

Official Documentation

MCP Specification: https://modelcontextprotocol.io/ (Latest: 2025-11-25)
MCP SDK: https://github.com/modelcontextprotocol/typescript-sdk
OpenAI Apps SDK: https://developers.openai.com/apps-sdk
MCP Apps Extension (SEP-1865): http://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/
Context7 Library ID: /modelcontextprotocol/typescript-sdk

Production Reference

Open Source Example: https://github.com/jezweb/chatgpt-app-sdk (portfolio carousel widget)

Live in Production: Rendering in ChatGPT Business
MCP Server: Full JSON-RPC 2.0 implementation with tools + resources (~310 lines)
Widget Integration: WordPress API → window.openai.toolOutput → React carousel
Database: D1 (SQLite) for contact form submissions
Stack: Hono 4 + React 19 + Tailwind v4 + Drizzle ORM
Key Files:

- /src/lib/mcp/server.ts - Complete MCP handler - /src/server/tools/portfolio.ts - Tool with widget annotations - /src/widgets/PortfolioWidget.tsx - Data access pattern

Verified: All 14 known issues prevented, zero errors in production

Community Resources

Deployment Tools

Cloudflare One-Click Deploy: Deploy MCP servers to Cloudflare Workers with pre-built templates and auto-configured CI/CD. Includes OAuth wrapper and Python support.

Frameworks

Skybridge (Community): React-focused framework with HMR support for widgets and enhanced MCP server helpers. Unofficial but actively maintained.

GitHub: https://github.com/alpic-ai/skybridge
Docs: https://www.skybridge.tech/

Note: Community frameworks are not officially supported. Use at your own discretion

适合场景

01

用户想查找某类 Agent Skill 时

02

需要根据任务场景推荐可安装能力包时

03

需要对比不同来源的安装命令和来源信息时

04

需要参考平台分布和安装热度时

能力概览

能力 1

按任务关键词查找相关 Skills

能力 2

展示可复制的安装命令

能力 3

保留来源站点、仓库和原始说明，方便继续核验

能力 4

补充不同宿主或平台的使用分布数据

能力 5

展示第三方安全扫描或审计结果

安装后应在对应宿主中按原始 README 的触发条件使用；具体调用方式请以来源页面和 README 为准。

平台分布

Claude Code

32.32%

按下载量换算1,298

Antigravity

22.48%

按下载量换算903

Gemini CLI

18.72%

按下载量换算752

OpenCode

14.34%

按下载量换算576

Cursor

7.21%

按下载量换算289

Codex

3.37%

按下载量换算135

安全审计

Gen Agent Trust Hub

未通过

Socket

通过

Snyk

通过

权限和风险

external-service

该 Skill 可能调用第三方服务、云服务或外部模型 API，使用前需要确认账号、额度、数据发送范围和服务条款。

安装前确认

本站仅展示第三方公开信息，不托管安装包，不提供自动安装或运行环境。安装前应自行审查源码、依赖和命令行为。来源安全扫描存在 warning/failed 结果，不能写成本站确认安全。来源字段存在多来源差异，先按来源优先级自动处理，无法消解时进入异常复核队列。

来源信息

GitHub 仓库

github.com

/jezweb/claude-skills

SKILL.md 来源

github.com

/jezweb/claude-skills/tree/main/skills/openai-apps-mcp

skills-sh

skills.sh

/jezweb/claude-skills/openai-apps-mcp

agentskills-to

agentskills.to

/jezweb/claude-skills/openai-apps-mcp

继续浏览同类 Skills

更多前端设计 Skills（10,216）返回 Skills 目录

上一个 Skill

open-pr（公开公关）

open-pr 用于处理 GitHub 仓库、Issue、Pull Request 和代码协作信息，适合在 Codex、Claude、Cursor、Gemini CLI 中需要围绕仓库状态、代码变更或协作事项进行整理时使用。可结合来源仓库、安装命令和原始 README 继续核验具体用法。安装前建议确认权限范围、维护状态，以及是否会触发联网、命令执行或文件读写。

下一个 Skill

openai-develop-web-game（OpenAI develop WEB game 命令行）

openai-develop-web-game 用于处理 GitHub 仓库、Issue、Pull Request 和代码协作信息，适合在 Codex、Claude、Cursor、Gemini CLI 中需要围绕仓库状态、代码变更或协作事项进行整理时使用。可结合来源仓库、安装命令和原始 README 继续核验具体用法。安装前建议确认权限范围、维护状态，以及是否会触发联网、命令执行或文件读写。

openai-apps-mcp（OpenAI apps MCP 问题管理）

安装方式

简介

SKILL.md

Building OpenAI Apps with Stateless MCP Servers

Overview

Quick Start

1. Scaffold & Install

2. Configure wrangler.jsonc

3. Create MCP Server (src/index.ts)

4. Create Widget (src/widgets/hello.html)

5. Deploy

Critical Requirements

Known Issues Prevention

Issue #1: CORS Policy Blocks MCP Endpoint

Issue #2: Widget Returns 404 Not Found

Issue #3: Widget Displays as Plain Text

Issue #4: ASSETS Binding Undefined

Issue #5: SSE Connection Drops After 100 Seconds

Issue #6: ChatGPT Doesn't Suggest Tool

Issue #7: Widget Can't Access Initial Data

Issue #8: Widget Scripts Blocked by CSP

Issue #9: Hono Global Response Override Breaks Next.js (v1.25.0-1.25.2)

Issue #10: Elicitation (User Input) Fails on Cloudflare Workers

Issue #11: SSE Transport Statefulness Breaks Serverless Deployments

Issue #12: OAuth Configuration Requires TWO Separate Apps

Issue #13: Widget State Over 4k Tokens Causes Performance Issues (Community-sourced)

Issue #14: Widget-Initiated Tool Calls Fail Without Permission Flag (Community-sourced)

Widget Development Best Practices

File Upload Limitations (Community-sourced)

Tool Performance Targets (Community-sourced)

MCP SDK 1.25.x Updates (December 2025)

Zod 4.0 Migration Notes (MAJOR UPDATE - July 2025)

Dependencies

Official Documentation

Production Reference

Community Resources

Deployment Tools

Frameworks

适合场景

能力概览

平台分布

安全审计

权限和风险

来源信息

继续浏览同类 Skills

3. Create MCP Server (`src/index.ts`)

4. Create Widget (`src/widgets/hello.html`)