Merge pull request #505 from basementstudio/canary

v0.6.5

Author: valebearzotti

apps/website/app/api/og/[...path]/route.tsx

@@ -162,11 +162,11 @@ function resolveOgContent(
       return {
         ok: true,
         content: {
-          title: "Shaping the future of MCP tooling",
+          title: "Examples & templates",
           description:
-            "xmcp now supports building compatible UI resources and tools with the OpenAI Apps SDK, out of the box.",
+            "Quickstart with xmcp using real-world examples and best practices.",
           summary: undefined,
-          date: "2025-12-11",
+          date: undefined,
         },
       };
     }

apps/website/content/blog/apps-sdk.mdx

@@ -10,15 +10,19 @@ previewImage: "/blog/apps-sdk.png"
 xmcp now supports building and serving UI resources compatible with OpenAI's Apps SDK. Get started by running:
 
 ```bash
-npx create-xmcp-app --gpt
+npx create-xmcp-app@latest
 ```
 
 <Video
   src="https://j2fbnka41vq9pfap.public.blob.vercel-storage.com/videos/gpt-apps-2.mp4"
   controls
 />
 
-The `--gpt` flag scaffolds a project with the necessary files and dependencies to get you up and running quickly.
+<Callout variant="warning">
+  OpenAI now supports MCP Apps. This post contains legacy context, so older
+  syntax examples may be outdated. New projects should use the MCP App template
+  and `_meta.ui` metadata.
+</Callout>
 
 Once your project is set up, you'll find two main folders. The prompts folder is excluded from this template by default, but you can easily enable it by modifying the `xmcp.config.ts` file.
 
@@ -52,42 +56,40 @@ For more information on constructing resource URIs, check out the [resources doc
 
 This folder contains your tools, which interact with and retrieve your UI resources.
 
-The `ToolMetadata` includes a `_meta` property for adding Apps SDK-specific metadata, enabling your resources to be displayed within widgets.
+The `ToolMetadata` includes a `_meta.ui` property for MCP Apps metadata, enabling your resources to be displayed within widgets.
 
 Available metadata keys:
 
-- `openai/outputTemplate`: Points to your resource URI template (required for discoverability)
-- `openai/widgetAccessible`: Boolean indicating if the resource is accessible within a widget
-- `openai/resultCanProduceWidget`: Boolean indicating if the tool result can produce a widget
-- `openai/widgetDescription`: Description displayed to the model when a client renders the component
-- `openai/widgetPrefersBorder`: Enables border rendering for widgets better suited to a "Card" layout
+- `ui.csp.connectDomains`: Origins allowed for fetch/XHR/WebSocket calls
+- `ui.csp.resourceDomains`: Origins for images, scripts, stylesheets, and media
+- `ui.domain`: Optional dedicated subdomain for your widget sandbox origin
+- `ui.prefersBorder`: Requests a bordered card layout for widgets
 
 ```typescript
 import { type ToolMetadata } from "xmcp";
 
-const widgetMeta = {
-  "openai/outputTemplate": "ui://widget/your-ui-resource.html",
-  "openai/widgetAccessible": true,
-  "openai/resultCanProduceWidget": true,
-};
-
 export const metadata: ToolMetadata = {
   name: "get-your-ui-resource",
   description: "Show Your UI Resource",
   _meta: {
-    ...widgetMeta,
+    ui: {
+      csp: {
+        connectDomains: ["https://api.example.com"],
+        resourceDomains: ["https://cdn.example.com"],
+      }
+    },
   },
 };
 
 export default async function handler() {
   return {
-    _meta: widgetMeta, // Required: return metadata in the response
+    content: [{ type: "text", text: "Widget ready" }],
   };
 }
 ```
 
-If you're not returning content in the response, you can omit the `content` array property and simply return the widget metadata.
+If you don't need CSP or rendering hints, you can omit `_meta.ui` entirely.
 
 ## References
 
-For more details, see the [OpenAI Apps SDK documentation](https://developers.openai.com/apps-sdk). You can test your resources and tools using [MCPJam](https://mcpjam.com), an open source MCP inspector.
+For more details, see the [MCP Apps docs](https://modelcontextprotocol.github.io/ext-apps/api/) and [OpenAI Apps SDK docs](https://developers.openai.com/apps-sdk). You can test your resources and tools using [MCPJam](https://mcpjam.com), an open source MCP inspector.

apps/website/content/blog/build-and-submit-gpt-apps.mdx

@@ -17,6 +17,12 @@ Learn how to submit your ChatGPT App to the OpenAI directory. We'll cover everyt
   build guide [here](/blog/doom-with-xmcp).
 </Callout>
 
+<Callout variant="warning">
+  OpenAI now supports MCP Apps. Some legacy syntax you may see in older guides
+  can be outdated, so prefer the current MCP Apps metadata format (`_meta.ui`)
+  in your implementation.
+</Callout>
+
 ## First steps
 
 If you don't have your assets ready, this is the moment to prepare them. The checklist includes:
@@ -52,7 +58,7 @@ You will need to explain why each permission is needed or not. Be specific about
 
 Next, you will need to verify your domain by serving the token provided by OpenAI at the path `/.well-known/openai-apps-challenge`.
 
-If you're using xmcp standalone mode, this route is automatically generated for you after setting the `OPENAI-APPS-VERIFICATION-TOKEN` environment variable. If you're using adapter mode, you'll need to create it manually.
+If you're using xmcp standalone mode, this route is automatically generated for you after setting the `OPENAI_APPS_VERIFICATION_TOKEN` environment variable. If you're using adapter mode, you'll need to create it manually.
 
 ## Testing
 

apps/website/content/docs/core-concepts/css.mdx

@@ -3,7 +3,7 @@ title: CSS
 description: Style your xmcp tools with Tailwind CSS, CSS, or CSS Modules
 ---
 
-If you're using [ChatGPT widgets](/docs/core-concepts/tools#openai-metadata) or [MCP Apps](/docs/core-concepts/tools#mcp-apps-metadata), xmcp provides your application multiple ways to use CSS:
+If you're using [MCP Apps](/docs/core-concepts/tools#mcp-apps-metadata), xmcp provides your application multiple ways to use CSS:
 
 - [Tailwind CSS](#tailwind-css)
 - [CSS](#css)

apps/website/content/docs/core-concepts/tools.mdx

@@ -177,55 +177,11 @@ annotations: {
   about when and how to call your tools, but they don't enforce any behavior.
 </Callout>
 
-### OpenAI Metadata
-
-For ChatGPT widget integration, add OpenAI-specific metadata under `_meta.openai`:
-
-```typescript
-export const metadata: ToolMetadata = {
-  name: "show-analytics",
-  description: "Display analytics dashboard",
-  _meta: {
-    openai: {
-      // Tool-specific
-      widgetAccessible: true,
-      toolInvocation: {
-        invoking: "Loading analytics...",
-        invoked: "Dashboard ready!",
-      },
-
-      // Resource-specific (for auto-generated widgets)
-      widgetDescription: "Real-time analytics dashboard",
-      widgetPrefersBorder: true,
-      widgetCSP: {
-        connect_domains: ["https://api.analytics.com"],
-        resource_domains: ["https://cdn.analytics.com"],
-      },
-    },
-  },
-};
-```
-
-**Tool-specific properties:**
-
-- `widgetAccessible` - Enable widget-to-tool communication (required for widgets)
-- `toolInvocation.invoking` - Message shown while executing (≤64 chars)
-- `toolInvocation.invoked` - Message shown after completion (≤64 chars)
-- `outputTemplate` - Custom widget URI (auto-generated if not provided)
-
-**Resource-specific properties:**
-
-- `widgetDescription` - Human-readable widget summary
-- `widgetPrefersBorder` - UI rendering hint for borders
-- `widgetCSP` - Content Security Policy for external resources
-- `widgetDomain` - Optional dedicated subdomain
-- `widgetState` - Initial state object passed to widget
-
 ### MCP Apps metadata
 
 <Callout variant="info">
-  Unlike OpenAI widgets, MCP Apps do not require specific metadata
-  configuration. Widgets work automatically without additional setup.
+  MCP Apps widgets work automatically for React tools. Add `ui` metadata only
+  when you need CSP or rendering hints.
 </Callout>
 
 ```typescript
@@ -300,9 +256,8 @@ export default async function calculate({
 
 ### 2. Template Literal Handlers
 
-Return HTML directly to create interactive widgets in ChatGPT. When you return HTML and include OpenAI metadata, xmcp automatically generates a widget resource.
-
-To enable widgets, you need to add the `_meta.openai` configuration in your metadata with `widgetAccessible: true`.
+Return HTML directly to create interactive widgets. xmcp automatically generates
+the widget resource.
 
 ```typescript title="src/tools/show-chart.ts"
 import { type ToolMetadata } from "xmcp";
@@ -311,11 +266,9 @@ export const metadata: ToolMetadata = {
   name: "show-chart",
   description: "Display an interactive chart",
   _meta: {
-    openai: {
-      widgetAccessible: true,
-      toolInvocation: {
-        invoking: "Loading chart...",
-        invoked: "Chart loaded!",
+    ui: {
+      csp: {
+        resourceDomains: ["https://cdn.jsdelivr.net"],
       },
     },
   },
@@ -339,8 +292,6 @@ export default async function showChart() {
 
 Return React components for interactive, composable widgets. xmcp renders the component to HTML and generates a widget resource automatically.
 
-To enable widgets, you need to add the `_meta.openai` configuration in your metadata with `widgetAccessible: true`.
-
 ```typescript title="src/tools/interactive-todo.tsx"
 import { type ToolMetadata } from "xmcp";
 import { useState } from "react";
@@ -349,12 +300,8 @@ export const metadata: ToolMetadata = {
   name: "interactive-todo",
   description: "Interactive todo list widget",
   _meta: {
-    openai: {
-      widgetAccessible: true,
-      toolInvocation: {
-        invoking: "Loading todo list...",
-        invoked: "Todo list ready!",
-      },
+    ui: {
+      prefersBorder: true,
     },
   },
 };

apps/website/content/docs/getting-started/installation.mdx

@@ -27,11 +27,11 @@ On installation, you'll see the following prompts:
 
 <TerminalPrompt>
   {
-    "? What is your project named? (my-xmcp-app)\n? Select a template: (Use arrow keys)\n❯ Default (Standard MCP server)\n  GPT App (ChatGPT/OpenAI widgets)\n  MCP App (React widgets for ext-apps)"
+    "? What is your project named? (my-xmcp-app)\n? Select a template: (Use arrow keys)\n❯ Default (Standard MCP server)\n  MCP App (React widgets for ext-apps)"
   }
 </TerminalPrompt>
 
-You can also skip prompts using flags: `--gpt` (GPT App), `--ui` (MCP App), `--tailwind` or `--tw` (Tailwind CSS). Run `npx create-xmcp-app --help` for all options.
+You can use `--ui` to scaffold the MCP App template (non-tailwind), or use `--tailwind` / `--tw` when selecting the MCP App template interactively. Run `npx create-xmcp-app --help` for all options.
 
 <TerminalPrompt>
   {

examples/ext-apps/src/tools/counter.tsx

@@ -8,7 +8,7 @@ export const metadata: ToolMetadata = {
 };
 
 export const schema = {
-  initialCount: z.number().describe("The name of the user to greet"),
+  initialCount: z.number().describe("The initial count value"),
 };
 
 export default function handler({ initialCount }: InferSchema<typeof schema>) {

…les/open-ai-react-css-modules/.gitignore examples/mcp-app-css-modules/.gitignoreexamples/open-ai-react-css-modules/.gitignore renamed to examples/mcp-app-css-modules/.gitignore examples/open-ai-react-css-modules/.gitignore renamed to examples/mcp-app-css-modules/.gitignore

@@ -1,8 +1,8 @@
 {
-  "name": "ChatGPT React CSS Modules",
-  "description": "Learn how to set up an xmcp server using ChatGPT widgets using React + CSS modules and single tool handlers",
+  "name": "MCP App React CSS Modules",
+  "description": "Learn how to set up an xmcp server using MCP app widgets with React + CSS modules and single tool handlers",
   "keywords": [
-    "chatgpt"
+    "mcp-app"
   ],
   "scripts": {
     "build": "xmcp build",