phidea
← ChatGPT nano build guide
Reference · page 6 / 6

# 6. Pitfalls & resources

Part 6 of 6. ← Testing & publishing · Index

6.1 Common pitfalls on day one

  1. Wrong annotations. Marking a tool that writes data as readOnlyHint: true — instant review rejection.
  2. Over-broad input schema. z.record(z.any()) catch-alls get flagged as data hoovering.
  3. Telemetry bleeding into `structuredContent`. Trace IDs, timings, internal SKU IDs show up to the model and to reviewers.
  4. Widget can't find tool output. Forgetting to re-render on openai:set_globals, or reading window.openai.toolOutput before the bridge initialises.
  5. CSP blocks your fetch. You hit an API that isn't in connectDomains — widget silently fails.
  6. ngrok URL rotated. Free ngrok URLs change on restart; ChatGPT connector goes stale. Pin a reserved domain or use Cloudflare Tunnel.
  7. SSE vs. Streamable HTTP mismatch. Inspector uses --transport http for Streamable HTTP; use --transport sse if you chose SSE. Mismatches look like a hang.
  8. Forgotten CORS preflight. Inspector needs OPTIONS /mcp to return 204 with the right headers.
  9. Widget bundles stale. If you update the template, bump the resource URI (e.g., ui://widget/todo.html?v=2) — ChatGPT caches aggressively.
  10. OAuth discovery 404. No /.well-known/oauth-protected-resource or missing registration_endpoint → ChatGPT can't complete DCR and shows a generic auth error.
  11. Chrome 142 local-network flag. Dev-time only, but costs an hour if you don't know.
  12. Demo account with MFA. Guaranteed rejection — reviewers can't get in.

6.2 Resources (verified 2026-04-24)

Official docs

  • Apps SDK overview: https://developers.openai.com/apps-sdk
  • Quickstart: https://developers.openai.com/apps-sdk/quickstart
  • Build your MCP server: https://developers.openai.com/apps-sdk/build/mcp-server
  • Build your ChatGPT UI: https://developers.openai.com/apps-sdk/build/chatgpt-ui
  • MCP concept page: https://developers.openai.com/apps-sdk/concepts/mcp-server
  • Reference (_meta, window.openai, annotations, JSON-RPC methods): https://developers.openai.com/apps-sdk/reference
  • Security & Privacy guide: https://developers.openai.com/apps-sdk/guides/security-privacy
  • App submission guidelines: https://developers.openai.com/apps-sdk/app-submission-guidelines
  • App Developer Terms: https://openai.com/policies/developer-apps-terms/
  • MCP servers for ChatGPT Apps & API: https://developers.openai.com/api/docs/mcp

Code

  • Official examples: https://github.com/openai/openai-apps-sdk-examples
  • Apps SDK UI component library: https://github.com/openai/apps-sdk-ui
  • MCP spec: https://modelcontextprotocol.io

Announcements

  • DevDay 2025 announcement: https://openai.com/index/introducing-apps-in-chatgpt/
  • "Developers can now submit apps to ChatGPT": https://openai.com/index/developers-can-now-submit-apps-to-chatgpt/

Adjacent / useful

  • OpenAI API rate limits (for upstream calls): https://platform.openai.com/docs/guides/rate-limits
  • Stytch's Apps SDK auth walkthrough (third-party): https://stytch.com/blog/guide-to-authentication-for-the-openai-apps-sdk/