OpenAI Apps SDK explained: How ChatGPT apps run on MCP

TL;DR: The OpenAI Apps SDK is a thin wrapper over MCP primitives, not a new protocol. It maps tools, resources, and prompts onto MCP concepts almost one-to-one, so the learning curve is minimal. The real decision is distribution: ChatGPT-native apps get access to ChatGPT's user base, while MCP-native apps get portability across clients. Either way, OAuth flows, token refresh, credential storage, and audit logging remain your engineering team's responsibility unless you adopt a managed layer. The maintenance burden, not the protocol, is the variable that determines total cost.

OpenAI's Apps SDK announcement created a new question for engineering teams already invested in MCP: is this a fork, a wrapper, or a replacement? The answer determines whether you spend a sprint or a quarter building your integration layer.

The wrong call burns senior engineer time on OAuth plumbing that does not differentiate your product, or locks your team into a distribution channel you cannot leave. This article maps how the OpenAI Apps SDK is built to MCP primitives, identifies the infrastructure you still need to build, and provides a build-vs-buy decision framework based on engineering hours and maintenance burden.

Understanding how the OpenAI Apps SDK is built

The OpenAI Apps SDK turns an MCP server into a ChatGPT app by adding a host runtime layer. You define tools on your server, attach UI resources that ChatGPT renders in an iframe, and test the full flow in Developer Mode before directory submission, as described in the OpenAI Apps SDK examples. The SDK uses MCP for the wire format, tool definitions, UI rendering, and security model, then adds a thin layer with ChatGPT-specific extensions like the window.openai.requestCheckout payment hook and store directory.

Defining the SDK functional boundary

The SDK renders UI widgets inside ChatGPT, registers tools, and handles tool dispatch. It does not handle authentication, credential storage, token refresh, or audit logging. The SDK is a host runtime, not an integration layer. You build the guest logic that runs inside ChatGPT's host environment; the host manages conversation, dispatches tool calls, and renders your UI, while your server manages business logic, data access, and external API connections.

The OpenAI Apps SDK examples show that results can include extra metadata such as inline HTML for rendering rich UI components alongside assistant messages. The SDK expects hosts to handle OAuth flows, with MCP authorization spec requirements including the host publishing OAuth metadata from your authorization server.

Mapping SDK logic to MCP protocols

The SDK maps almost one-to-one onto MCP primitives: tools to tools, resources to resources, prompts to prompts, with tool registration structurally identical to MCP tool registration.

The Anthropic MCP specification defines JSON-RPC messages for communication between Clients and Servers, with servers supporting three primitives: Prompts, Resources, and Tools. The Apps SDK extends MCP so developers can design both the logic and interface of their apps, as OpenAI's announcement confirms.

Comparing ChatGPT-native and MCP-native apps

ChatGPT-native apps get distribution inside ChatGPT's interface and access to its user base, with UI rendering via SDK widgets and a host-managed runtime. MCP-native apps get portability across any MCP client and guest-managed logic. Interface rendering is not exclusive to the SDK: MCP Apps is a shared standard for app interfaces that is now supported in ChatGPT, Claude, Goose, and VS Code. The trade-off is distribution versus portability, not capability.

The Apps SDK adds ChatGPT-specific extensions, such as the window.openai APIs and the store directory, that only run inside ChatGPT, creating a distribution wrapper rather than a new protocol, as described in the MCP vs Apps SDK comparison. The app interface itself is not tied to ChatGPT, because MCP Apps provides a shared standard for it across multiple clients.

Mapping OpenAI Apps SDK calls to MCP actions

Tool definitions in both the Apps SDK and MCP are built around a name, a description, and an input schema, with optional metadata for UI hints.

Core MCP primitives for OpenAI SDK

Each primitive appears in the SDK's API surface with structural equivalence to its MCP counterpart.

Here is a tool definition in the OpenAI Apps SDK format:

server.registerTool("generate_story", {
  title: "Generate Story",
  description: "Generates creative stories based on plot",
  inputSchema: {
    plot: z.string().min(50).max(1000)
  }
});

The MCP equivalent uses the same JSON Schema structure:

{
  "name": "generate_story",
  "description": "Generates creative stories based on plot",
  "inputSchema": {
    "type": "object",
    "properties": {
      "plot": { "type": "string", "minLength": 50, "maxLength": 1000 }
    }
  }
}

Mapping SDK runtime to MCP environments

The SDK runtime is the ChatGPT host; MCP environments are any MCP client. The host provides UI rendering, session management, and tool dispatch, while the guest provides tool logic, resource access, and prompt templates.

The request flow follows this path: ChatGPT receives a user message, and the model decides to call a tool. ChatGPT dispatches the call to your MCP server. Your server executes the tool and returns structured content. ChatGPT renders any associated UI widgets.

Registering tools via the OpenAI Apps SDK

Tool registration looks identical whether you build ChatGPT-native or MCP-native, which means your team is not learning a new protocol.

Mapping SDK tools to MCP schemas

The registration process follows three steps:

1. List tools: Your server advertises the tools it supports, including their JSON Schema input/output contracts and optional annotations such as readOnlyHint.

2. Call tools: When a model selects a tool, it issues a call_tool request with arguments that match the user intent. Your server executes the action and returns structured content.

3. Return widgets: Alongside structured content, return embedded resources in the response metadata so the Apps SDK can render the interface inline.

How the OpenAI SDK handles tool calls

Tool calls are dispatched by the host, not the guest. The SDK handles UI rendering and user interaction, while the guest handles tool logic and returns results. Your tool logic remains portable across MCP clients, while the SDK handles ChatGPT-specific rendering.

Here is a tool call handler example:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  
<p>  if (name === "generate_story") {
    const story = await generateStory(args.plot);
    return {
      content: [{ type: "text", text: story }],
      _meta: {
        "openai/outputTemplate": "ui://widget/story.html"
      }
    };
  }
});</p>

How the Apps SDK handles authentication

The SDK uses OAuth 2.1 and OIDC standards, with ChatGPT acting as the OAuth public client on behalf of the user, while your backend serves as the protected resource, and an identity layer handles client registration, consent, and token management.

Integrating OAuth via OpenAI Apps SDK

The SDK provides OAuth 2.1 and OIDC standard support, metadata discovery via well-known endpoints, and token exchange protocol definition. It does not provide OAuth consent screen hosting, token storage or encryption, token refresh automation, credential revocation, or audit logging.

How OpenAI Apps SDK handles secrets

The SDK does not handle secrets; credentials live in your infrastructure. The risk is credentials ending up in application code or the LLM context.

A managed credential vault removes that risk. Composio stores tokens in an AES-256 encrypted vault, isolated from application code and the LLM context window, and enforces access policies in the request path before the model is involved.

Managing token expiry and renewal

Token refresh is a guest responsibility. When a token expires, the tool call fails, and the user must re-authenticate.

ChatGPT does not pre-emptively refresh tokens. The next time your user makes a request that involves an action, ChatGPT searches its secret store for your access token, and if the expiry date has passed, it will call /oauth/token again with the refresh token, as documented in the OpenAI community guide.

Building OAuth for three enterprise SaaS tools in-house creates three separate maintenance obligations, and each upstream API change lands directly on your engineering team's calendar.

Infrastructure requirements for ChatGPT apps

Running a ChatGPT app in production requires infrastructure beyond the SDK. The minimum config hides the auth and token management work that becomes apparent only after go-live.

Minimum config for ChatGPT app runs

To run a ChatGPT app, you need a registered app, a tool server, and a credential store. Managed containers like Fly.io or Render offer quick deployment with automatic TLS, and cloud serverless options like Google Cloud Run work well if scale-to-zero is required.

Production deployment requirements:

• MCP Server (HTTP/SSE) exposing tools and resources

• OAuth Authorization Server handling client registration and token exchange

• Credential/Secret Storage for access and refresh tokens

• Database for user state and tool outcomes

• Monitoring/Logging for tool calls, errors, and latency

Infrastructure and compliance prerequisites

Enterprise security questionnaires will ask about credential storage, access controls, and audit logs. The SDK provides none of these.

The real governance issue is whether teams can enforce durable authorization, user context, and server-side control across chat-driven workflows. As general practice, harden server-side scope checks by having your MCP server validate OAuth scopes and token claims on every tool invocation, including refresh and reauthorization paths.

Composio holds SOC 2 Type II and ISO/IEC 27001:2022 certifications, with pre-filled compliance documentation that helps IT teams respond to enterprise questionnaires with structured, ready-to-share evidence. Pointing to existing certifications is typically faster than assembling documentation from multiple systems.

Should you build ChatGPT-native, MCP-native, or both?

The decision depends on your distribution goals and your team's capacity for ongoing maintenance. The protocol investment is minimal either way, the infrastructure burden is identical, and the variable that determines total cost is who maintains the OAuth and credential layer.

When ChatGPT-native is the right fit

ChatGPT-native makes sense when distribution inside ChatGPT is the primary goal. You gain access to ChatGPT's user base and the store directory, but portability is limited to the ChatGPT host.

When to build for the MCP standard

MCP-native makes sense when portability across clients is the primary goal, which typically applies when your product surfaces in multiple AI environments (Claude Desktop, Cursor, VS Code) rather than optimizing for a single distribution channel. The trade-off is giving up ChatGPT-specific extensions such as window.openai.requestCheckout and the ChatGPT store directory. Interface rendering remains available through MCP Apps, a shared standard supported in ChatGPT, Claude, Goose, and VS Code, and the same OAuth and credential infrastructure is reusable across clients.

Weighing the OpenAI Apps SDK design

The SDK is a distribution wrapper, not a new protocol. The real decision is about where your app lives, not what it can do.

Ongoing maintenance: SDK vs MCP

Day 1 is when your integration goes live; Day 100 is when the upstream API changes its authentication model or OpenAI updates the SDK. What breaks and who fixes it determines your long-term maintenance burden.

Developers face issues with UI updates and asset loading in ChatGPT Apps SDK due to how widget HTML templates are cached, a known limitation documented in this GitHub issue, leading to broken or stale UI and forcing repeated app resubmission cycles for UI-only changes.

Whether you build ChatGPT-native, MCP-native, or both, the OAuth and credential infrastructure underneath is the same, and it is the part that breaks your sprint velocity and stalls your enterprise deals. Composio's managed layer handles the full token lifecycle across 1,500+ connectors. When your next enterprise prospect asks where credentials are stored, Composio's centralized vault with AES-256 encryption gives you a documented answer backed by SOC 2 Type II and ISO/IEC 27001:2022 certifications.

Authentication is where most teams get stuck first, but it is the entry point rather than the full job. Once credentials are handled, Composio's action infrastructure executes agent tool calls across 50,000+ tools and 1B+ tool calls, with self-learning capabilities that improve how agents execute those actions over time, so your team spends its sprints on agent logic instead of integration upkeep.

Book a call to walk through your security requirements before the next enterprise review.

FAQs

Can I use existing MCP servers with the Apps SDK?

Yes, with adaptation. The SDK maps onto MCP primitives, so existing MCP servers can be wrapped for ChatGPT. How long adaptation takes depends on your server and UI complexity: you add ChatGPT-specific metadata for UI rendering, test the full flow in Developer Mode, and handle the store submission process.

What happens when OpenAI updates the SDK?

Your app may break. The SDK is a proprietary distribution channel, so plan for updates that change behavior and test against each release. MCP-native apps are insulated from ChatGPT-specific SDK changes, but they still depend on the MCP spec, which can also change.

How does the Apps SDK handle authentication failures?

It does not. Authentication is the guest's responsibility. When a token expires or a refresh fails, the tool call fails, and the user must re-authenticate. A managed OAuth layer handles refresh cycles automatically and provides fallback mechanisms when upstream APIs change their authentication models.

Key terms glossary

MCP (Model Context Protocol): A specification for connecting AI models to external tools and data sources. Defines primitives for tools, resources, and prompts using JSON-RPC messages between Clients and Servers.

Tool registration: The process of declaring a tool's schema and handler so a host can dispatch calls to it. In the SDK, this maps to MCP tool registration using JSON Schema for input validation.

MCP primitives: The three core concepts in MCP: tools (actions the model can perform), resources (data the model can access), and prompts (predefined interaction templates). The SDK maps onto all three with structural equivalence.

ChatGPT-native app: An app built with the OpenAI Apps SDK that runs inside ChatGPT. It uses the SDK's UI rendering and tool dispatch, but authentication remains the developer's responsibility.

OAuth token lifecycle: The full sequence of consent, token issuance, refresh, and expiry. Managing this lifecycle is the primary maintenance burden for any integration, and it is not handled by the Apps SDK.