ChatGPT Apps SDK Quickstart

Step-by-step quickstart

1. Step 1

   Install the SDK and scaffold a server

   Start with the official Node or Python SDK. Both give you a working hello-world server in under a minute. The scaffolded server registers a single example tool and prints its endpoint URL — that's everything you need to point ChatGPT at it for local testing.

   # Node
   npm create openai-app@latest my-app
   cd my-app
   npm install
   npm run dev
   
   # Python
   pip install openai-apps-sdk
   openai-apps init my-app
   cd my-app
   python -m my_app

2. Step 2

   Define your first tool

   A tool is a single named action your app exposes. Give it a verb_noun name, document its parameters with descriptions a non-technical reader could follow, and return a JSON-serializable result. The model reads your descriptions to decide when to call the tool, so the description is the most important code you'll write today.

   // Node — TypeScript
   import { defineTool } from "openai-apps-sdk";
   
   export const search_docs = defineTool({
     name: "search_docs",
     description:
       "Search the user's documentation for a keyword and return up to 5 matching titles with snippets. Use this when the user asks about content stored in their docs. Do NOT use this for generic web search.",
     parameters: {
       query: {
         type: "string",
         description: "The search keyword or phrase.",
       },
     },
     async handler({ query }, { userId }) {
       const results = await myBackend.search(userId, query);
       return { results };
     },
   });

3. Step 3

   Add OAuth (or a simpler auth mode)

   If your app accesses user-specific data, ship OAuth from day one. The SDK's OAuth helper handles the redirect and token storage; you implement the provider side (or use your existing OAuth provider). For tools that don't touch user data, you can ship without auth and still publish — but most useful apps need it.

   // Node — register OAuth
   import { configureOAuth } from "openai-apps-sdk";
   
   configureOAuth({
     authorizationUrl: "https://myapp.com/oauth/authorize",
     tokenUrl: "https://myapp.com/oauth/token",
     scopes: ["docs:read"],
   });

4. Step 4

   Run it locally inside ChatGPT

   The dev mode opens a tunneled connection so a real ChatGPT session can call your local server. You connect once from your developer account; subsequent code changes are picked up on save. This is the loop you'll iterate on for the entire build — getting tool descriptions and parameter shapes right is empirical, not theoretical.

   # Start dev tunnel + register with ChatGPT
   npm run dev:tunnel
   
   # Then in ChatGPT, open the apps picker:
   # Settings → Developer → Connect local app

5. Step 5

   Write the manifest and metadata

   The manifest describes your app to ChatGPT and to the directory: name, description, icon, category, scopes, privacy policy URL, terms URL. Keep names short and brand-aligned (not 'AI Helper for X'), and write the description as the user-visible promise of what the app does in chat.

   // openai-app.json
   {
     "name": "MyDocs",
     "description": "Search and summarize your team's documentation from chat.",
     "category": "productivity",
     "icon": "./assets/icon.png",
     "scopes": [
       { "name": "docs:read", "description": "Read your documentation pages." }
     ],
     "policies": {
       "privacy": "https://myapp.com/privacy",
       "terms": "https://myapp.com/terms"
     }
   }

6. Step 6

   Deploy to a real endpoint

   Host the server anywhere with stable HTTPS. The endpoint must be production-grade (not staging) when you submit, because reviewers run real prompts against it. Add health checks, monitoring, and an abuse contact email that someone actually reads.

   # Vercel example
   vercel --prod
   
   # Or Cloudflare Workers
   wrangler deploy
   
   # Note the production URL and add it to openai-app.json

7. Step 7

   Submit through the developer dashboard

   Once your endpoint is live and your manifest is locked, submit through the OpenAI Apps SDK dashboard. The submission flow is detailed in our companion guide — see the link at the bottom of this page. Expect days, not weeks, for first review response.

Common pitfalls

The mistakes we see most often when reviewing apps. None of these are showstoppers — they're all fast to fix once you know to look for them.

• ⚠Tool descriptions written for engineers instead of for the model — make them readable to a non-technical user
• ⚠One giant 'do_action' tool with a dozen parameters instead of N specific verbs
• ⚠OAuth scopes broader than the tools actually need
• ⚠Missing the negative case in tool descriptions ('do NOT use this for X')
• ⚠Returning huge unstructured strings instead of small structured objects
• ⚠Production endpoint with no health check or monitoring
• ⚠Submitting before stress-testing at least 20 real prompts

Frequently asked questions