User                    Web UI                Host                Widget (iframe)         MCP Server
 │                        │                    │                       │                    │
 │ Enter "View Tokyo weather"     │                    │                       │                    │
 │──────────────────────▶│                    │                       │                    │
 │                        │  Pass the prompt to the model │                       │                    │
 │                        │───────────────────▶│                      │                    │
 │                        │                    │ The model decides to call show_weather │                    │
 │                        │                    │─────────────────────────────────────────▶ │
 │                        │                    │                       │     server executes    │
 │                        │                    │                       │     Return toolResult  │
 │                        │                    │◀──────────────────────────────────────────│
 │                        │                    │ See _meta.ui          │                   │
 │                        │                    │ Prefetch widget HTML       │                   │
 │                        │                    │──────────────────────────────────────────▶│
 │                        │                    │◀──────────────────────────────────────────│
 │                        │                    │ Attach to the tool call message    │                    │
 │                        │                    │ widget metadata         │                    │
 │                        │◀───────────────────│                      │                    │
 │                        │ Render sandbox iframe │                       │                    │
 │                        │ Inject HTML + CSP    │                       │                    │
 │                        │──────────────────────────────────────────▶│                    │
 │                        │                    │                       │  initialize        │
 │                        │                    │◀─────────────────────│                    │
 │                        │                    │ Push toolResult       │                    │
 │                        │                    │─────────────────────▶│                    │
 │                        │                    │ Push hostContext.theme │                   │
 │                        │                    │─────────────────────▶│                    │
 │ See weather dashboard ✓        │                    │                       │ Apply theme and render UI   │
 │                        │                    │                       │                    │
 │ Click "San Francisco"   │                    │                       │                    │
 │───────────────────────────────────────────────────────────────────▶│                    │
 │                        │                    │                       │ Call tools/call      │
 │                        │                    │◀──────────────────────│ get_weather(SF)   │
 │                        │ ⚠ Dialog: Allow? │                       │                    │
 │ Click "Allow"              │                    │                       │                    │
 │──────────────────────▶│                    │                       │                    │
 │                        │                    │ Forward to server         │                    │
 │                        │                    │─────────────────────────────────────────▶ │
 │                        │                    │◀──────────────────────────────────────────│
 │                        │                    │ Return the result to the widget      │                    │
 │                        │                    │─────────────────────▶│                    │
 │ See SF weather ✓        │                    │                       │ Partial refresh           │

const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
const {
  CallToolRequestSchema,
  ListToolsRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
} = require('@modelcontextprotocol/sdk/types.js');

const UI_MIME = 'text/html;profile=mcp-app';
const TODO_URI = 'ui://my-todo/list';

const server = new Server(
  { name: 'my-todo', version: '0.1.0' },
  { capabilities: { tools: {}, resources: {} } },
);

const todos = [];

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'show_todos',
      description: 'Show interactive todo list widget',
      inputSchema: { type: 'object', properties: {} },
      // Key: Declare the UI Resource. When the host sees this field, it renders the widget.
      _meta: { ui: { resourceUri: TODO_URI } },
    },
    {
      name: 'add_todo',
      description: 'Add a new todo',
      inputSchema: {
        type: 'object',
        properties: { title: { type: 'string' } },
        required: ['title'],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async req => {
  if (req.params.name === 'show_todos') {
    return {
      content: [{ type: 'text', text: `${todos.length} todos` }],
      // structuredContent is automatically pushed to the widget as toolResult.
      structuredContent: { items: todos },
      // Key: The tool result also carries _meta.ui, allowing the host to associate it with the widget.
      _meta: { ui: { resourceUri: TODO_URI } },
    };
  }
  if (req.params.name === 'add_todo') {
    todos.push({ id: todos.length + 1, title: req.params.arguments.title });
    return {
      content: [{ type: 'text', text: 'Added' }],
      structuredContent: { items: todos },
    };
  }
});

server.setRequestHandler(ListResourcesRequestSchema, async () => ({
  resources: [{ uri: TODO_URI, name: 'todo-list', mimeType: UI_MIME }],
}));

server.setRequestHandler(ReadResourceRequestSchema, async req => {
  if (req.params.uri === TODO_URI) {
    return {
      contents: [{
        uri: TODO_URI,
        text: HTML,           // See the HTML template below.
        mimeType: UI_MIME,
        _meta: {
          ui: {
            // CSP: Declares the external domains required by the widget at runtime, which the host injects into the iframe.
            // <meta http-equiv="Content-Security-Policy">. **Domains not listed will be blocked by the browser.**
            csp: {
              // Allows importing ext-apps remotely via ESM (both script-src and connect-src require esm.sh)
              resourceDomains: ['https://esm.sh'],
              // If the widget also calls external APIs (fetch / WebSocket), add the corresponding domains here.
              connectDomains: ['https://esm.sh'],
            },
            permissions: {},     // Default sandbox: allow-scripts allow-same-origin allow-forms
            prefersBorder: true, // The host adds a 1px border to the iframe for visual distinction.
          },
        },
      }],
    };
  }
});

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />

  <!--
    CSP: Keep it consistent with the domains declared in the resource's _meta.ui.csp.
    The host automatically injects the script-src / connect-src allowlist based on _meta.ui.csp.
    However, the <meta> tag written in the HTML takes precedence. It is recommended to declare it as well for convenient local preview.
  -->
  <meta http-equiv="Content-Security-Policy"
        content="default-src 'self' 'unsafe-inline';
                 script-src 'self' 'unsafe-inline' https://esm.sh;
                 connect-src 'self' https://esm.sh;
                 img-src 'self' data: blob:;
                 style-src 'self' 'unsafe-inline';">

  <style>
    /* Two-level theme adaptation (see the "Theme Adaptation" section for details) */
    :root {
      color-scheme: light dark;
      --bg: light-dark(#fff, #1e1e1e);
      --fg: light-dark(#1a1a1a, #e6e6e6);
    }
    html[data-theme="light"] { color-scheme: light }
    html[data-theme="dark"]  { color-scheme: dark }
    body { margin: 0; padding: 12px; background: var(--bg); color: var(--fg); }
  </style>
</head>
<body>
  <ul id="list"></ul>

  <script type="module">
    // Import ext-apps remotely via ESM (a self-contained bundle that the browser can import directly)
    // Lock the version to 1.x to avoid upstream breaking changes. For production, pin it to a specific patch version (such as @1.7.4).
    import { App } from 'https://esm.sh/@modelcontextprotocol/ext-apps@1/app-with-deps';

    const app = new App({
      name: 'todo-widget',
      version: '1.0.0',
      autoResize: true,        // Automatically report size-changed based on the content.
    });

    function render(items) {
      const list = document.getElementById('list');
      list.textContent = '';
      for (const t of items) {
        const li = document.createElement('li');
        li.textContent = t.title;
        list.appendChild(li);
      }
    }

    // When the model calls show_todos, it pushes the toolResult over.
    app.ontoolresult = (r) => {
      if (r?.structuredContent?.items) render(r.structuredContent.items);
    };

    // Theme: After obtaining hostContext.theme, write data-theme + style.colorScheme.
    function applyTheme(theme) {
      if (!theme) return;
      document.documentElement.setAttribute('data-theme', theme);
      document.documentElement.style.colorScheme = theme;
    }
    app.onhostcontextchanged = (ctx) => applyTheme(ctx?.theme);

    await app.connect();
    applyTheme(app.hostContext?.theme);
  </script>
</body>
</html>

{
  "mcpServers": {
    "my-todo": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}

{
  "mcpServers": {
    "my-todo": {
      "type": "http",
      "url": "http://127.0.0.1:8801/mcp"
    }
  }
}

// ~/.codebuddy/settings.json
{
  "permissions": {
    "allow": [
      "mcp__my-todo",                 // Allow all tools on the entire server.
      "mcp__github__list_issues",     // Allow only the list_issues tool on the github server.
      "mcp__github__get_pr_diff"
    ],
    "deny": [
      "mcp__github__delete_repo"      // Even if the entire server is allowed, a single tool can still be precisely denied.
    ]
  }
}

codebuddy --allowed-tools "mcp__my-todo,mcp__github__list_issues" "..."

:root {
  color-scheme: light dark;
  --bg: light-dark(#fff, #1e1e1e);
  --fg: light-dark(#1a1a1a, #e6e6e6);
  --border: light-dark(#ddd, #3a3a3a);
}

/* When JS locks data-theme, it overrides the automatic value from light-dark() */
html[data-theme="light"] { color-scheme: light }
html[data-theme="dark"]  { color-scheme: dark }

body { background: var(--bg); color: var(--fg); }

function applyTheme(theme) {
  if (!theme) return;  // If theme is not available, do not touch the DOM. Let CSS light-dark() take over as the fallback.
  document.documentElement.setAttribute('data-theme', theme);
  document.documentElement.style.colorScheme = theme;
}

applyTheme(app.hostContext?.theme);
app.onhostcontextchanged = (ctx) => applyTheme(ctx?.theme);

app.log({ level: 'info', logger: 'my-widget', data: { foo: 'bar' } });