Rork × OpenAI Apps SDK: Ship a ChatGPT-Embedded App From Your Rork Codebase

Making the Model Pick the Right Tool: Descriptions, Annotations, and Instructions

Registering a tool doesn't mean the model will reach for it. All ChatGPT can see is the name, the description, and the argument schema. When those are thin, a user says "help me get organized this week," no tool fires, and the model answers from general knowledge instead.

Here is a before and after from my own server.

Length is not what made the difference. What made the difference was stating both when to call it and when not to. Adding one sentence about the negative case visibly cut mix-ups between neighbouring tools. The same goes for describe() on each argument: "Task title" invites a bland paraphrase, while "copy the user's own wording" preserves what they actually said. These are prompts wearing the costume of type definitions.

The MCP TypeScript SDK also offers registerTool, which takes a config object and lets you declare annotations and outputSchema alongside the description. Where your SDK version supports it, this shape is easier to live with.

server.registerTool(
  "delete_task",
  {
    title: "Delete Task",
    description: "Call only when the user explicitly asks to delete. To mark something finished, call complete_task instead.",
    inputSchema: z.object({ task_id: z.string() }),
    annotations: { destructiveHint: true, idempotentHint: true },
  },
  async ({ task_id }, ctx) => { /* ... */ }
);

Annotations are hints for the client, not the model. A tool marked readOnlyHint can run without a confirmation prompt; one marked destructiveHint gets one. Forgetting the hint on a delete tool is how conversational momentum turns into deleted data.

Rules that span tools belong in the server's instructions, not in any single description:

const server = new McpServer(
  { name: "task-app", version: "1.0.0" },
  {
    instructions:
      "Always call list_tasks before updating or completing a task. Lists are capped at 50 items. If the user hasn't mentioned a date, omit due_date rather than guessing.",
  }
);

Clients are expected to surface instructions near the system prompt, so it shouldn't repeat what the tool descriptions already say. Keep it to ordering, limits, and things the model must not infer on its own.

One more lever: how you return errors changes how the model behaves. If your handler throws, the SDK still turns it into an error result, but what reaches the model is a raw exception string. Returning isError: true yourself lets you write the correction in your own words.

if (due_date && !isValidDate(due_date)) {
  return {
    content: [
      { type: "text", text: `due_date must be YYYY-MM-DD. Received: ${due_date}` },
    ],
    isError: true,
  };
}

After that one branch went in, date-format mismatches started resolving themselves mid-conversation. The user sees nothing; the model retries with the right shape. Write error text as instructions addressed to the model rather than to a human reading a log, and accuracy climbs.

Reshaping Rork's React Components Into ChatGPT UI Resources

In Apps SDK, a UI is an HTML resource registered under a ui:// URI and bound to a "render" tool. The binding lives in the tool definition's _meta.ui.resourceUri (_meta["openai/outputTemplate"] is accepted as a compatibility alias) — not in the tool's return value. The docs say to attach it only to the render tool; data tools just return structuredContent so the model can fetch first and render afterwards.

const TEMPLATE_URI = "ui://task-card/v1";
 
server.registerResource(
  "task-card",
  TEMPLATE_URI,
  { mimeType: "text/html;profile=mcp-app" },
  async () => ({
    contents: [{ uri: TEMPLATE_URI, mimeType: "text/html;profile=mcp-app", text: TASK_CARD_HTML }],
  })
);
 
server.registerTool(
  "show_task_card",
  {
    description: "Show one task as a card. Pass content you just fetched with list_tasks.",
    inputSchema: { taskId: z.string() },
    _meta: { ui: { resourceUri: TEMPLATE_URI } },
  },
  async ({ taskId }) => ({ structuredContent: { taskId } })
);

If the HTML loads external scripts or images, declare the allowed domains in the resource's _meta.ui.csp (connectDomains / resourceDomains); nested frames are blocked by default. The UI itself can be React-based. The trick that keeps this cheap is treating Rork's React Native components as a logic-and-tokens layer, then writing thin Web wrappers for the UI Resources.

// apps-sdk/src/ui/task-card.tsx
import type { FC } from "react";
import { useTaskById } from "@core/hooks/useTaskById";
 
export const TaskCard: FC<{ taskId: string }> = ({ taskId }) => {
  const task = useTaskById(taskId);
  if (!task) return <div>Loading…</div>;
  return (
    <div className="task-card" data-task-id={task.id}>
      <h3>{task.title}</h3>
      {task.dueDate && <p>Due: {task.dueDate}</p>}
      <button
        onClick={() => window.openai?.callTool("complete_task", { id: task.id })}
      >
        Mark complete
      </button>
      <a href={`https://yourapp.com/open?task=${task.id}`}>Open in app</a>
    </div>
  );
};

window.openai is the browser-side bridge inside UI Resources. Buttons round-trip through the MCP server and re-render the card, so you can carry small interactions to completion without ever leaving the chat. The "Open in app" link is a Universal Link that hands users off to Rork for anything that's faster on a mobile UI — and the handoff design is what makes this whole architecture earn its keep.

For styling, ChatGPT exposes CSS variables that adapt to its dark and light modes. If your Rork side keeps design tokens in a shared package (palette, spacing, radii), porting them to Web costs almost nothing. I learned the hard way that hard-coded colors in a UI Resource look great in light mode and unreadable in dark mode; the variable approach removes the guesswork.

A practical detail about layout: ChatGPT renders UI Resources at a constrained width — often around 360 to 480 pixels depending on the viewport. Build for that envelope. If your Rork mobile screens already work at iPhone widths, the same constraints apply. Avoid horizontal scrolling within the card, and prefer compact vertical lists with clear tap targets. Anything more than three to five interactive elements per card starts to feel cluttered inside the conversation.

Sharing One User Identity Across ChatGPT and the Mobile App

This is the most common place to crash in production. Apps SDK authentication follows the MCP authorization spec: OAuth 2.1, authorization-code flow with PKCE, so you can bind a ChatGPT user to your service's account. Your authorization server should advertise S256 in code_challenge_methods_supported, validate the resource parameter on both authorization and token requests, and issue tokens whose audience is your MCP server. The MCP server publishes /.well-known/oauth-protected-resource. Client-ID metadata documents (CIMD) are preferred for registration, DCR works if you expose a registration_endpoint, and machine-to-machine grants such as client credentials are not supported. The trap is that your Rork app already has its own auth, and a naive integration doubles the user table.

The pattern I use is a "reverse" flow: from inside the Rork app, the user taps "Connect ChatGPT" and starts the OAuth dance with the ChatGPT side as the relying party. New users still get the standard ChatGPT-initiated flow; existing paying users get the in-app flow. Both land on the same row in the users table.

// apps-sdk/src/auth/oauth.ts
import { Hono } from "hono";
import { createSession, findOrCreateUser } from "@shared/auth";
 
const auth = new Hono<{ Bindings: Env }>();
 
auth.get("/oauth/authorize", async (c) => {
  const { client_id, redirect_uri, state, code_challenge } = c.req.query();
 
  const rorkSession = c.req.cookie("rork_session");
  if (rorkSession) {
    const code = await issueAuthCode(c.env, {
      userId: await getUserIdFromRorkSession(rorkSession),
      clientId: client_id,
      codeChallenge: code_challenge,
    });
    return c.redirect(`${redirect_uri}?code=${code}&state=${state}`);
  }
 
  return c.redirect(`/login?return=${encodeURIComponent(c.req.url)}`);
});
 
auth.post("/oauth/token", async (c) => {
  const { code, code_verifier, client_id } = await c.req.parseBody();
  const verified = await verifyAuthCode(c.env, code as string, code_verifier as string);
  if (!verified) return c.json({ error: "invalid_grant" }, 400);
 
  const accessToken = await createSession(c.env, {
    userId: verified.userId,
    scope: "apps_sdk",
    ttlSeconds: 3600,
  });
  const refreshToken = await createRefreshToken(c.env, verified.userId);
 
  return c.json({
    access_token: accessToken,
    refresh_token: refreshToken,
    token_type: "Bearer",
    expires_in: 3600,
  });
});

Tag Apps-SDK-issued sessions with their own scope (scope: "apps_sdk"). Six months from now you'll want "ChatGPT can read but not edit" or "ChatGPT can't see billing details" — and you'll be glad the scope dimension was already there. PKCE (the code_challenge and code_verifier pair) is mandatory; don't skip it because OpenAI's clients won't.

One subtle behavior: when a user disconnects your app from ChatGPT's settings, OpenAI sends a revocation webhook to your /oauth/revoke endpoint. Make sure you actually invalidate the tokens server-side and remove the apps_sdk scope from that session. I've seen integrations skip this step and leave revoked sessions running for hours — a security and trust failure both.

Handing Off Conversations to the Mobile App With Universal Links

"Talk to ChatGPT for five minutes, finish the job in the app" turns out to be a surprisingly common shape of session. People love using natural language to plan and triage; they love a real touch UI for reordering, editing details, and closing out tasks. Universal Links are how you stitch the two together.

Set up Apple Universal Links and Android App Links by hosting apple-app-site-association and assetlinks.json from the same Cloudflare Worker.

// apps-sdk/src/universal-links.ts
app.get("/.well-known/apple-app-site-association", (c) => {
  return c.json({
    applinks: {
      details: [
        {
          appIDs: ["TEAMID.com.yourapp.mobile"],
          components: [
            { "/": "/open*", comment: "ChatGPT deep links" },
            { "/": "/articles/*" },
          ],
        },
      ],
    },
  });
});
 
app.get("/open", async (c) => {
  // Embed a correlation ID so we can measure how often ChatGPT links convert
  const correlationId = c.req.query("cid");
  const target = c.req.query("task");
  if (correlationId) {
    await c.env.DB.prepare(
      "INSERT INTO chatgpt_to_app_opens (correlation_id, target, opened_at) VALUES (?, ?, ?)"
    ).bind(correlationId, target, new Date().toISOString()).run();
  }
 
  // Fall back to the App Store if the app isn't installed
  return c.html(`
    <script>
      window.location.href = "yourapp://task/${target}";
      setTimeout(() => {
        window.location.href = "https://apps.apple.com/app/idXXXXXXXXX";
      }, 1500);
    </script>
  `);
});

The latency budget from "Open in app" tap to the right screen rendering is two seconds — past that, users feel friction and bounce. Pass state through URL query params and let the Rork side's deep link handler swap screens immediately, before the network call resolves. With Expo Router, a (stack)/task/[id].tsx file that reads the param and kicks off the fetch in the same render is usually all you need.

Don't forget the analytics value of the correlation ID. If you log it on both sides — ChatGPT outbound and Rork inbound — you can compute the actual handoff success rate, which is one of the most important metrics for the entire integration. In my own data the handoff success rate is around 60 to 70 percent; the rest are users who don't have the app installed, on a desktop browser, or on a platform where Universal Links don't trigger. Knowing this number lets you prioritize the App Store fallback path properly.

Keeping Pricing and Billing Coherent Across Both Surfaces

Apps SDK runs primarily on OpenAI's credit envelope for tool calls, but anything that requires your subscription (advanced reports, unlimited tasks) needs to be billed through your own service. ChatGPT allows opening external URLs, so the practical pattern is to issue a Stripe Checkout session and return its URL.

server.tool(
  "upgrade_to_pro",
  "Call only when the user asks to move to a paid plan. If they merely ask about pricing, answer without calling this.",
  { plan: z.enum(["monthly", "yearly"]) },
  async ({ plan }, ctx) => {
    const userId = await resolveUserId(ctx, c.env.DB);
    const session = await stripe.checkout.sessions.create({
      mode: "subscription",
      line_items: [{ price: PRICE_IDS[plan], quantity: 1 }],
      client_reference_id: userId,
      success_url: "https://yourapp.com/upgrade-success?from=chatgpt",
      cancel_url: "https://yourapp.com/upgrade-cancel",
      metadata: { source: "chatgpt_apps_sdk", plan_type: plan },
    });
    return {
      content: [
        {
          type: "text",
          text: `Here's your upgrade link: ${session.url}`,
        },
      ],
      structuredContent: { checkoutUrl: session.url },
    };
  }
);

Stamp metadata.source: "chatgpt_apps_sdk" on every Stripe session that originates from the Apps SDK side, and source: "rork_app" on the mobile side. When you eventually want to know whether ChatGPT-acquired users have higher LTV than App Store ones, your data is already cut by channel. Keep prices identical across surfaces — a ChatGPT user who hears one number and sees another in your app loses trust instantly. A single pricing.ts module that both surfaces import from solves this for free.

If you operate in multiple regions, consider serving the Stripe Checkout session in the user's regional currency. Apps SDK passes the user's locale through context, and Stripe supports auto-localization through automatic_payment_methods. Combining the two gives a smoother experience for international users without forcing you to maintain price IDs per locale.

Testing the Integration Locally Before Submission

Before you submit your Apps SDK manifest to OpenAI for review, you can iterate locally with the developer console. The flow looks like this: run your MCP server on localhost, expose it through a tunnel like cloudflared tunnel so it has a public URL, and register the URL in the developer dashboard as a test integration. Your own ChatGPT account can then call the tools as if it were a real user.

A few guardrails that save time during this stage. First, log every MCP request and response to your own database during development, including the raw payloads. The official developer dashboard shows transcripts but is sometimes delayed; your own logs let you reproduce issues immediately. Second, write a small integration test suite that hits your /mcp endpoint with hand-crafted MCP envelopes. The Apps SDK ecosystem has a few utilities for this, but a simple Vitest file with fetch calls is enough to catch regressions before they hit production. Third, make sure your test ChatGPT account is a separate user from your real account; the developer console hooks let test integrations bypass certain safety checks, and you don't want those rules accidentally relaxed for your daily-driver account.

Once functional testing is green, do a manual round-trip exercise: install the integration, do five different real conversations covering normal usage, edge cases, and error states, and time how long each round-trip takes. If any tool consistently exceeds five seconds even on a fast network, refactor it before you submit. Reviewers do try the integration in real conversations, and slow tools are a common rejection reason. In my own experience, the difference between a one-week approval and a three-week back-and-forth often comes down to whether tool calls feel snappy from the very first interaction the reviewer has.

Checking This Guide Against the Official Docs (October 9, 2026)

Before revising this article, I compared every code sample against the official documentation. I had assumed the code I pasted late one night would simply run; the places where it didn't only showed up as type errors.

I confirmed handleRequest from the type definitions shipped inside the SDK package. What I have not done is observe the actual traffic ChatGPT sends, so headers and other wire-level details are limited to what the docs state.

Before pasting any code, check the import line against the SDK's type definitions once. I keep that habit even on days when I'm in a hurry.

Production Pitfalls I've Hit (And How to Skip Them)

A few things only show up under real load, and almost all of them have 30-minute fixes if you know they exist.

MCP response-time pressure. I could not find a documented timeout value, so I treat ten seconds as my own budget. If your tool kicks off heavy work — multi-step external API calls, long generations — you need a "show progress immediately, deliver the rest async" pattern using Server-Sent Events or polling. I once chained three Notion API calls inside a single tool and pushed past twelve seconds; ChatGPT showed a timeout error. The fix was to return the first item immediately and let the others stream in.

UI template caching. A template URI such as ui://task-card/v1 can be reused by the client. If you ship new HTML and still see the old look, bump the version segment (v1 → v2). Pass changing data through structuredContent rather than the URI, and the problem mostly disappears.

Refresh-token lifetime. Your authorization server decides it, not ChatGPT. Track each user's last access and pick a policy yourself — for example, require re-authorization after 30 days of silence — so you are never surprised by a 401 in production.

Image hosting and CORS. UI Resources can only display images from absolute URLs hosted with proper CORS headers. R2 or any CDN with Access-Control-Allow-Origin: * works. Sharing the asset bundle with the Rork side via something like @rork/assets is the cheapest path.

Privacy and data retention. Information you obtain through Apps SDK is governed by stricter rules than the average mobile-acquired user. Maintain a separate retention policy page for chatgpt_apps_sdk users and link it from your standard privacy policy. Treat this as table stakes, not nice-to-have.

Rate limit headroom. Apps SDK can call your tools far more aggressively than a typical mobile user opens an app. A user having a five-minute conversation might trigger eight to fifteen tool calls. If your downstream APIs (Notion, Supabase, Stripe) have rate limits, plan for the bursty traffic shape. I add per-user token-bucket rate limiting on my MCP server itself so a single chatty user can't accidentally take the integration down for everyone else.

Distribution Strategy: From the App Directory to Mobile ASO

Building the integration is half the job; getting it discovered is the other half. ChatGPT's App Directory (or its successor surface) is where your integration becomes findable. Application copy that focuses on conversational use cases beats feature lists by a wide margin. "A task manager" is generic; "When you ask 'What should I work on this week?', this app pulls from your past notes, drafts a list, and hands tasks off to mobile for daily execution" tells the reviewer exactly what value the integration adds.

Once users tap through from ChatGPT into your Rork app, switch onboarding behavior. They've already had a focused conversation about their problem; they don't need the standard feature tour. Read the correlation_id from the deep link, skip onboarding for that session, and drop them on the relevant screen with the context already loaded. This single change typically lifts ChatGPT-sourced first-day retention significantly.

On the ASO side, mention the integration in your store description: "Talk to this app inside ChatGPT — say '...' to start." After I added one line like this to a store listing, conversion felt like it moved up over the following weeks — but other changes shipped at the same time, so I can't give you an isolated number. Apps SDK isn't only a distribution layer — it's also a credibility cue inside the App Store. The same logic applies to Google Play. Reviewers and users both see "works with ChatGPT" as a quality signal in 2026.

For deeper integration into your marketing funnel, consider making one or two of your most popular tool flows shareable as conversation starter templates. ChatGPT users often pass URLs back and forth that pre-fill prompts; if you provide a shareable URL like https://chatgpt.com/?model=gpt-4&prompt=...&app=task-manager, you create organic word-of-mouth distribution that doesn't require any paid acquisition spend.

Observability: Knowing What Conversations Are Doing

The hardest part of running an Apps SDK integration in production isn't writing the tools — it's knowing what's happening when something feels off. ChatGPT users don't file bug reports the same way mobile users do; they just stop using the integration. You need observability that catches problems before users churn.

Three signals are worth tracking from day one. First, tool invocation latency: log the wall-clock time from MCP request received to MCP response sent for every single tool call, broken out by tool name. A regression from 800ms to 4 seconds in list_tasks will silently kill engagement, and you won't notice without this metric. Second, error rate per tool: how often does each tool throw an exception, return an empty result, or trigger an OAuth failure? I send these to a Cloudflare Workers Analytics Engine dataset and graph them in Grafana. Third, conversation-length distribution: how many tool calls happen in a single user session before the user moves on? A long tail of single-call sessions usually means your tools are not being chained well in the model's reasoning, often because tool descriptions are too vague.

Pair these metrics with a small alerts rule. If error_rate > 5% over a 15-minute window for any tool, fire to Slack. If p95_latency > 6s for any tool, fire to Slack. These two alerts catch most production fires before users notice them. I also keep a daily digest that lists the top three tools by usage, top three errors, and the day-over-day delta in active users. Five minutes of reading the digest each morning replaces hours of guessing.

For deeper investigation, replay matters. Store the raw MCP envelope for every request and response (after sanitizing sensitive fields) in cold storage like R2 or S3. When a user reports "the integration acted weird yesterday," you can pull their session and see exactly what the model sent and what your server returned. This is also invaluable for fine-tuning tool descriptions over time: read through transcripts where the model called the wrong tool and tighten the descriptions of the tools it should have called instead.

Where to Start This Week

Don't try to build everything at once. Stand up /mcp with a single tool — list_tasks is a great choice — wire up a test OAuth client, and let the UI Resource render <div>{title}</div>. From there, your time is best spent on the handoff: the moment a ChatGPT conversation needs to continue inside the Rork app is where most of the user value sits.

ChatGPT is becoming a third storefront alongside the App Store and Google Play. Whether you can be present on all three by the end of 2026 is the kind of strategic question that compounds.