mcpbeat Sign in

OpenAI Apps MCP Agent Skill

by coco-research

| Build ChatGPT apps with MCP servers on Cloudflare Workers. Extend ChatGPT with custom tools and interactive widgets (HTML/JS UI).

7k tokens
context cost
the whole folder, loaded on every use
8
files
ships runnable scripts
0
copies elsewhere
how many repositories repackaged it
196
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/coco-research/coco --skill OpenAI Apps MCP

The instruction itself

35 sections, as written by the author

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/[email protected], [email protected], [email protected], [email protected]

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/[email protected] [email protected] [email protected]
npm install -D @cloudflare/[email protected] [email protected]

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/[email protected] → 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 [email protected] → 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.

  • Docs: https://developers.cloudflare.com/agents/guides/remote-mcp-server/
  • Blog: https://blog.cloudflare.com/model-context-protocol/

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

Other skills for the same job

different authors, same section of the catalogue
MCP Deploy Manage Agents
by github
vendor ×1

Skill converted from mcp-deploy-manage-agents.prompt.md

2k tokens
Cloud Claw Launch Agent
by internet-court
×1

Use this skill when the user wants to launch a new AltClaw, OpenClaw, PicoClaw, or Ottie deployment through Cloud Claw. Covers the same user-facing fields and constraints exposed in the Cloud Claw UI, using the local altllm cloud-claw-* commands. Do NOT use for post-launch lifecycle tasks like start/stop/delete/logs; use cloud-claw-manage-vm.

1k tokens
Hosted Agents V2 Py
by lingxling
×1

Build hosted agents using Azure AI Projects SDK with ImageBasedHostedAgentDefinition. Use when creating container-based agents in Azure AI Foundry.

2k tokens
Cloudflare MCP Server
by ComeOnOliver
×1

Build MCP (Model Context Protocol) servers on Cloudflare Workers with tools, resources, and prompts.

49k tokens scripts
When Chaining Agent Pipelines Use Stream Chain
by ComeOnOliver
×1

Chain agent outputs as inputs in sequential or parallel pipelines for data flow orchestration

5k tokens
Clone Audit Mrlv3nl4
by nexu-io

Audit cloned or reimplemented websites for fidelity gaps, tracking scripts, source-brand and language residue, placeholders, and risky external dependencies. Use before handoff or deployment, or when asked to review a website clone for cleanup and readiness.

2k tokens
Hermes Tweet
by wshobson

> Install and operate Hermes Tweet, a Hermes Agent plugin for X/Twitter research, timeline reading, tweet analysis, and approval-gated tweet actions. Use this skill when installing Hermes Tweet, researching X/Twitter accounts, monitoring launch signals, investigating mentions, auditing giveaways, or preparing guarded tweet actions. Use proactively when a Hermes Agent workflow needs current X/Twitter context. Requires XQUIK_API_KEY for read and action tools.

2k tokens
Arize Evaluator
by github
vendor

Handles LLM-as-judge evaluation workflows on Arize including creating/updating evaluators, running evaluations on spans or experiments, managing tasks, trigger-run operations, column mapping, and continuous monitoring. Use when the user mentions create evaluator, LLM judge, hallucination, faithfulness, correctness, relevance, run eval, score spans, score experiment, trigger-run, column mapping, continuous monitoring, or improve evaluator prompt.

10k tokens

How to use it

Copy the folder

Take coco-research/openai apps mcp from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.

Install what it needs

The instructions reference npm, npx. Without those the skill loads but fails at the first command.