Anatomy of a ChatGPT App

Every ChatGPT App is made of two layers: the MCP Server (mandatory) and the Web Widget (optional). Understanding how these layers communicate -- and what each is responsible for -- is the foundation for everything else in this course.

The MCP Server Layer

Your MCP server is the brain of your app. It defines:

• Tools: Functions the model can call. Each tool has a name, description, input schema, and handler.
• Resources: Data the model can read. Think of these as read-only endpoints -- configuration files, documentation, knowledge bases.
• Prompts: Pre-written templates the model can use. Useful for complex workflows with specific output formats.

For most ChatGPT Apps, you will primarily use tools. Resources and prompts are useful for advanced scenarios.

The Single Endpoint

Unlike traditional REST APIs with multiple routes, an MCP server exposes a single endpoint: /mcp. All communication flows through this endpoint using JSON-RPC 2.0:

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "wireless headphones",
      "maxPrice": 100
    }
  },
  "id": 1
}

The MCP Apps Bridge

ChatGPT does not connect to your MCP server using the standard MCP transport (stdio or SSE). Instead, it uses the MCP Apps Bridge -- a server-sent events (SSE) transport optimized for the ChatGPT environment.

The bridge handles:

• Connection management (keep-alive, reconnection)
• Authentication token injection
• Rate limiting and abuse prevention
• Message routing between the model and your server

You do not need to implement the bridge yourself. The @modelcontextprotocol/sdk handles it when you configure the transport as sse.

The Web Widget Layer

The widget is an HTML page rendered in a sandboxed iframe inside the ChatGPT interface. It communicates with ChatGPT through the window.openai API -- a JavaScript bridge injected into the iframe.

The widget can:

• Call your MCP tools through window.openai.callTool()
• Send follow-up messages to the conversation through window.openai.sendFollowUpMessage()
• Upload files through window.openai.uploadFile()
• Request different display sizes through window.openai.requestDisplayMode()
• Share state with the model through window.openai.setWidgetState()

Component Types

ChatGPT can render tool responses as rich UI components without any widget code. These components are defined by the _meta field in your tool response:

Using components, you can build a rich, interactive app without writing any frontend code. The model calls your tools, your tools return structured data with component hints, and ChatGPT renders them beautifully.

Example: A Product Search Tool Response

{
  "content": [
    {
      "type": "text",
      "text": "Found 3 wireless headphones under $100"
    }
  ],
  "_meta": {
    "component": "shop",
    "items": [
      {
        "title": "SoundPro X1",
        "description": "Active noise cancellation, 30hr battery",
        "price": { "amount": 79.99, "currency": "USD" },
        "image_url": "https://example.com/x1.jpg",
        "action_url": "https://example.com/buy/x1"
      }
    ]
  }
}

ChatGPT renders this as a styled product card with image, price, and a buy button -- no HTML or CSS required from you.

When You Need a Widget vs When You Don't

This is the most important architectural decision you will make: