@doubao-dev/cli 1.0.0-rc.1 → 1.0.0-rc.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +12 -6
  2. package/dist/691.js +96 -0
  3. package/dist/build.js +1 -0
  4. package/dist/categories.js +1 -1
  5. package/dist/command.js +9 -3
  6. package/dist/command~1.js +4 -4
  7. package/dist/command~2.js +1 -1
  8. package/dist/command~3.js +2 -1
  9. package/dist/command~4.js +1 -1
  10. package/dist/command~5.js +6 -5
  11. package/dist/dist.js +1 -1
  12. package/dist/draft.js +2 -2
  13. package/dist/index.d.ts +886 -8
  14. package/dist/index.js +1 -1
  15. package/dist/main.d.ts +886 -8
  16. package/dist/main.js +1 -1
  17. package/dist/mcp-apps-inspector.js +1 -0
  18. package/dist/multipart-parser.js +1 -1
  19. package/dist/open.js +2 -0
  20. package/dist/plugin.js +2 -2
  21. package/dist/preview.js +5 -5
  22. package/dist/progress.js +1 -1
  23. package/dist/ratatui-ui.js +1 -1
  24. package/dist/session.js +1 -1
  25. package/dist/skills/doubao-plugin-cli/SKILL.md +45 -40
  26. package/dist/skills/doubao-plugin-cli/references/cli/development.md +128 -0
  27. package/dist/skills/doubao-plugin-cli/references/cli/project.md +190 -0
  28. package/dist/skills/doubao-plugin-cli/references/cli/release.md +144 -0
  29. package/dist/skills/doubao-plugin-cli/references/examples/todo-example.md +114 -0
  30. package/dist/skills/doubao-plugin-cli/references/examples/workbench-example.md +130 -0
  31. package/dist/skills/doubao-plugin-cli/references/protocols/business-skills.md +49 -0
  32. package/dist/skills/doubao-plugin-cli/references/protocols/cli-connectors.md +56 -0
  33. package/dist/skills/doubao-plugin-cli/references/protocols/managed-agents.md +46 -0
  34. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/integration.md +207 -0
  35. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/runtime.md +318 -0
  36. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-apps/workbench.md +180 -0
  37. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-auth.md +73 -0
  38. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-config.md +145 -0
  39. package/dist/skills/doubao-plugin-cli/references/protocols/mcp-events.md +260 -0
  40. package/dist/skills/doubao-plugin-cli/references/protocols/plugin-json.md +95 -0
  41. package/dist/skills/doubao-plugin-cli/references/protocols/workbench.md +120 -0
  42. package/dist/skills/doubao-plugin-cli/references/upstream/SOURCES.md +32 -0
  43. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.LICENSE +216 -0
  44. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-apps.mdx +1760 -0
  45. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-events.LICENSE +216 -0
  46. package/dist/skills/doubao-plugin-cli/references/upstream/mcp-events.md +1231 -0
  47. package/dist/skills/doubao-plugin-cli/references/upstream/standard-webhooks.LICENSE +201 -0
  48. package/dist/skills/doubao-plugin-cli/references/upstream/standard-webhooks.md +349 -0
  49. package/dist/skills/miaoda-mcp-dev/SKILL.md +20 -0
  50. package/dist/skills/miaoda-mcp-dev/references/app-plugin-mcp.md +9 -0
  51. package/dist/skills/miaoda-mcp-dev/references/development.md +62 -0
  52. package/dist/skills/miaoda-mcp-dev/references/todo-example.md +128 -0
  53. package/dist/templates/standard/AGENTS.md +1 -1
  54. package/dist/templates/workbench/README.md.template +9 -0
  55. package/dist/templates/workbench/com.doubao/workbench/manifest.json +10 -0
  56. package/dist/uninstall.js +1 -1
  57. package/dist/versions~1.js +1 -1
  58. package/dist/web/index.html +1 -0
  59. package/dist/web/sandbox-proxy.html +101 -0
  60. package/dist/web/static/css/index.b3102f16b9.css +1 -0
  61. package/dist/web/static/js/155.747f5232dc.js +69 -0
  62. package/dist/web/static/js/async/970.86106314b5.js +1 -0
  63. package/dist/web/static/js/index.c1186260b9.js +4 -0
  64. package/dist/web/static/js/lib-react.00514652bf.js +2 -0
  65. package/dist/web/static/js/lib-react.00514652bf.js.LICENSE.txt +39 -0
  66. package/dist/workbench-search.js +1 -0
  67. package/dist/xdg-open +1267 -0
  68. package/package.json +14 -15
  69. package/dist/21.js +0 -101
  70. package/dist/schema.js +0 -1
  71. package/dist/skills/doubao-plugin-cli/references/cli-connectors.md +0 -29
  72. package/dist/skills/doubao-plugin-cli/references/development.md +0 -29
  73. package/dist/skills/doubao-plugin-cli/references/mcp-apps.md +0 -40
  74. package/dist/skills/doubao-plugin-cli/references/mcp-auth.md +0 -23
  75. package/dist/skills/doubao-plugin-cli/references/project-config.md +0 -139
  76. package/dist/skills/doubao-plugin-cli/references/upload.md +0 -77
  77. /package/dist/{21.js.LICENSE.txt → 691.js.LICENSE.txt} +0 -0
@@ -0,0 +1,1760 @@
1
+ <!-- For full edit history, see specification/draft/apps.mdx. Local corrections are recorded in SOURCES.md. -->
2
+
3
+ # SEP-1865: MCP Apps: Interactive User Interfaces for MCP
4
+
5
+ **Track:** Extensions
6
+
7
+ **Authors:** Ido Salomon, Liad Yosef, Olivier Chafik, Jerome Swannack, Jonathan Hefner, Anton Pidkuiko, Nick Cooper, Bryan Ashley, Alexi Christakis
8
+
9
+ **Status:** Stable (2026-01-26)
10
+
11
+ **Created:** 2025-11-21
12
+
13
+ ## Abstract
14
+
15
+ This SEP proposes an extension (per SEP-1724) to MCP that enables servers to deliver interactive user interfaces to hosts. MCP Apps introduces a standardized pattern for declaring UI resources via the `ui://` URI scheme, associating them with tools through metadata, and facilitating bidirectional communication between the UI and the host using MCP's JSON-RPC base protocol. This extension addresses the growing community need for rich, interactive experiences in MCP-enabled applications, maintaining security, auditability, and alignment with MCP's core architecture. The initial specification focuses on HTML resources (`text/html;profile=mcp-app`) with a clear path for future extensions.
16
+
17
+ ## Motivation
18
+
19
+ MCP lacks a standardized way for servers to deliver rich, interactive user interfaces to hosts. This gap blocks many use cases that require visual presentation and interactivity that goes beyond plain text or structured data. As more hosts adopt this capability, there's a growing risk of fragmentation and interoperability challenges.
20
+
21
+ [MCP-UI](https://mcpui.dev/) has demonstrated the viability and value of MCP apps built on UI resources and serves as a community playground for the UI spec and SDK. Fuelled by a dedicated community, it developed the bi-directional communication model and the HTML, external URL, and remote DOM content types. MCP-UI's adopters, including hosts and providers such as Postman, HuggingFace, Shopify, Goose, and ElevenLabs, have provided critical insights and contributions to the community.
22
+
23
+ OpenAI's Apps SDK, launched in November 2025, further validated the demand for rich UI experiences within conversational AI interfaces. The Apps SDK enables developers to build rich, interactive applications inside ChatGPT using MCP as its backbone.
24
+
25
+ The architecture of both the Apps SDK and MCP-UI have both significantly informed the design of this specification.
26
+
27
+ However, without formal standardization:
28
+
29
+ - Servers cannot reliably expect UI support via MCP
30
+ - Each host may implement slightly different behaviors
31
+ - Security and auditability patterns are inconsistent
32
+ - Developers must maintain separate implementations or adapters for different hosts (e.g., MCP-UI vs. Apps SDK)
33
+
34
+ This SEP addresses the current limitations through an optional, backwards-compatible extension that unifies the approaches pioneered by MCP-UI and the Apps SDK into a single, open standard.
35
+
36
+ ## Specification
37
+
38
+ ### Extension Identifier
39
+
40
+ This extension is identified as: `io.modelcontextprotocol/ui`
41
+
42
+ ### Overview
43
+
44
+ MCP Apps extends the Model Context Protocol to enable servers to deliver interactive user interfaces to hosts. This extension introduces:
45
+
46
+ - **UI Resources:** Predeclared resources using the `ui://` URI scheme
47
+ - **Tool-UI Linkage:** Tools reference UI resources via metadata
48
+ - **Bidirectional Communication:** UI iframes communicate with hosts using standard MCP JSON-RPC protocol
49
+ - **Security Model:** Mandatory iframe sandboxing with auditable communication
50
+
51
+ This specification focuses on HTML content (`text/html;profile=mcp-app`) as the initial content type, with extensibility for future formats.
52
+
53
+ As an extension, MCP Apps is optional and must be explicitly negotiated between clients and servers through the extension capabilities mechanism (see Capability Negotiation section).
54
+
55
+ ### UI Resource Format
56
+
57
+ UI resources are declared using the standard MCP resource pattern with specific conventions:
58
+
59
+ ```typescript
60
+ interface UIResource {
61
+ /**
62
+ * Unique identifier for the UI resource
63
+ *
64
+ * MUST use the `ui://` URI scheme to distinguish UI resources from other
65
+ * MCP resource types.
66
+ *
67
+ * @example
68
+ * "ui://weather-dashboard"
69
+ */
70
+ uri: string;
71
+
72
+ /**
73
+ * Human-readable display name for the UI resource
74
+ *
75
+ * Used for listing and identifying the resource in host interfaces.
76
+ *
77
+ * @example
78
+ * "Weather Dashboard"
79
+ */
80
+ name: string;
81
+
82
+ /**
83
+ * Optional description of the UI resource's purpose and functionality
84
+ *
85
+ * Provides context about what the UI does and when to use it.
86
+ *
87
+ * @example
88
+ * "Interactive weather visualization with real-time updates"
89
+ */
90
+ description?: string;
91
+
92
+ /**
93
+ * MIME type of the UI content
94
+ *
95
+ * SHOULD be `text/html;profile=mcp-app` for HTML-based UIs in the initial MVP.
96
+ * Other content types are reserved for future extensions.
97
+ *
98
+ * @example
99
+ * "text/html;profile=mcp-app"
100
+ */
101
+ mimeType: string;
102
+
103
+ /**
104
+ * Resource metadata for security and rendering configuration
105
+ *
106
+ * Includes Content Security Policy configuration, dedicated domain settings,
107
+ * and visual preferences.
108
+ */
109
+ _meta?: {
110
+ ui?: UIResourceMeta;
111
+ }
112
+ }
113
+
114
+ interface McpUiResourceCsp {
115
+ /**
116
+ * Origins for network requests (fetch/XHR/WebSocket)
117
+ *
118
+ * - Empty or omitted = no external connections (secure default)
119
+ * - Maps to CSP `connect-src` directive
120
+ *
121
+ * @example
122
+ * ["https://api.weather.com", "wss://realtime.service.com"]
123
+ */
124
+ connectDomains?: string[],
125
+ /**
126
+ * Origins for static resources (images, scripts, stylesheets, fonts, media)
127
+ *
128
+ * - Empty or omitted = no external resources (secure default)
129
+ * - Wildcard subdomains supported: `https://*.example.com`
130
+ * - Maps to CSP `img-src`, `script-src`, `style-src`, `font-src`, `media-src` directives
131
+ *
132
+ * @example
133
+ * ["https://cdn.jsdelivr.net", "https://*.cloudflare.com"]
134
+ */
135
+ resourceDomains?: string[],
136
+ /**
137
+ * Origins for nested iframes
138
+ *
139
+ * - Empty or omitted = no nested iframes allowed (`frame-src 'none'`)
140
+ * - Maps to CSP `frame-src` directive
141
+ *
142
+ * @example
143
+ * ["https://www.youtube.com", "https://player.vimeo.com"]
144
+ */
145
+ frameDomains?: string[],
146
+ /**
147
+ * Allowed base URIs for the document
148
+ *
149
+ * - Empty or omitted = only same origin allowed (`base-uri 'self'`)
150
+ * - Maps to CSP `base-uri` directive
151
+ *
152
+ * @example
153
+ * ["https://cdn.example.com"]
154
+ */
155
+ baseUriDomains?: string[],
156
+ }
157
+
158
+ interface UIResourceMeta {
159
+ /**
160
+ * Content Security Policy configuration
161
+ *
162
+ * Servers declare which external origins their UI needs to access.
163
+ * Hosts use this to enforce appropriate CSP headers.
164
+ */
165
+ csp?: McpUiResourceCsp,
166
+ /**
167
+ * Sandbox permissions requested by the UI
168
+ *
169
+ * Servers declare which browser capabilities their UI needs.
170
+ * Hosts MAY honor these by setting appropriate iframe `allow` attributes.
171
+ * Apps SHOULD NOT assume permissions are granted; use JS feature detection as fallback.
172
+ */
173
+ permissions?: {
174
+ /**
175
+ * Request camera access
176
+ *
177
+ * Maps to Permission Policy `camera` feature
178
+ */
179
+ camera?: {},
180
+ /**
181
+ * Request microphone access
182
+ *
183
+ * Maps to Permission Policy `microphone` feature
184
+ */
185
+ microphone?: {},
186
+ /**
187
+ * Request geolocation access
188
+ *
189
+ * Maps to Permission Policy `geolocation` feature
190
+ */
191
+ geolocation?: {},
192
+ /**
193
+ * Request clipboard write access
194
+ *
195
+ * Maps to Permission Policy `clipboard-write` feature
196
+ */
197
+ clipboardWrite?: {},
198
+ },
199
+ /**
200
+ * Dedicated origin for view
201
+ *
202
+ * Optional domain for the view's sandbox origin. Useful when views need
203
+ * stable, dedicated origins for OAuth callbacks, CORS policies, or API key allowlists.
204
+ *
205
+ * **Host-dependent:** The format and validation rules for this field are
206
+ * determined by each host. Servers MUST consult host-specific documentation
207
+ * for the expected domain format. Common patterns include:
208
+ * - Hash-based subdomains (e.g., `{hash}.claudemcpcontent.com`)
209
+ * - URL-derived subdomains (e.g., `www-example-com.oaiusercontent.com`)
210
+ *
211
+ * If omitted, Host uses default sandbox origin (typically per-conversation).
212
+ *
213
+ * @example
214
+ * "a904794854a047f6.claudemcpcontent.com"
215
+ * @example
216
+ * "www-example-com.oaiusercontent.com"
217
+ */
218
+ domain?: string,
219
+ /**
220
+ * Visual boundary preference
221
+ *
222
+ * Boolean controlling whether a visible border and background is provided by the host. Specifying an
223
+ * explicit value for this is recommended because hosts' defaults may vary.
224
+ *
225
+ * - `true`: Request visible border + background
226
+ * - `false`: Request no visible border + background
227
+ * - omitted: host decides border
228
+ */
229
+ prefersBorder?: boolean,
230
+ }
231
+ ```
232
+
233
+ The resource content is returned via `resources/read`:
234
+
235
+ ```typescript
236
+ // resources/read response for UI resource
237
+ {
238
+ contents: [{
239
+ uri: string; // Matching UI resource URI
240
+ mimeType: "text/html;profile=mcp-app"; // MUST be "text/html;profile=mcp-app"
241
+ text?: string; // HTML content as string
242
+ blob?: string; // OR base64-encoded HTML
243
+ _meta?: {
244
+ ui?: {
245
+ csp?: {
246
+ connectDomains?: string[]; // Origins for network requests (fetch/XHR/WebSocket).
247
+ resourceDomains?: string[]; // Origins for static resources (scripts, images, styles, fonts).
248
+ frameDomains?: string[]; // Origins for nested iframes (frame-src directive).
249
+ baseUriDomains?: string[]; // Allowed base URIs for the document (base-uri directive).
250
+ };
251
+ permissions?: {
252
+ camera?: {}; // Request camera access
253
+ microphone?: {}; // Request microphone access
254
+ geolocation?: {}; // Request geolocation access
255
+ clipboardWrite?: {}; // Request clipboard write access
256
+ };
257
+ domain?: string;
258
+ prefersBorder?: boolean;
259
+ };
260
+ };
261
+ }];
262
+ }
263
+ ```
264
+
265
+ #### Content Requirements:
266
+
267
+ - URI MUST start with `ui://` scheme
268
+ - `mimeType` MUST be `text/html;profile=mcp-app` (other types reserved for future extensions)
269
+ - Content MUST be provided via either `text` (string) or `blob` (base64-encoded)
270
+ - Content MUST be valid HTML5 document
271
+
272
+ #### Host Behavior:
273
+
274
+ - **CSP Enforcement:** Host MUST construct CSP headers based on declared domains
275
+ - **Restrictive Default:** If `ui.csp` is omitted, Host MUST use:
276
+
277
+ ```
278
+ default-src 'none';
279
+ script-src 'self' 'unsafe-inline';
280
+ style-src 'self' 'unsafe-inline';
281
+ img-src 'self' data:;
282
+ media-src 'self' data:;
283
+ connect-src 'none';
284
+ ```
285
+
286
+ - **No Loosening:** Host MAY further restrict but MUST NOT allow undeclared domains
287
+ - **Audit Trail:** Host SHOULD log CSP configurations for security review
288
+
289
+ Example:
290
+
291
+ ```json
292
+ // Resource declaration
293
+ {
294
+ "uri": "ui://weather-server/dashboard-template",
295
+ "name": "weather_dashboard",
296
+ "description": "Interactive weather dashboard view",
297
+ "mimeType": "text/html;profile=mcp-app"
298
+ }
299
+
300
+ // Resource content with metadata
301
+ {
302
+ "contents": [{
303
+ "uri": "ui://weather-server/dashboard-template",
304
+ "mimeType": "text/html;profile=mcp-app",
305
+ "text": "<!DOCTYPE html><html>...</html>",
306
+ "_meta": {
307
+ "ui" : {
308
+ "csp": {
309
+ "connectDomains": ["https://api.openweathermap.org"],
310
+ "resourceDomains": ["https://cdn.jsdelivr.net"]
311
+ },
312
+ "prefersBorder": true
313
+ }
314
+ }
315
+ }]
316
+ }
317
+ ```
318
+
319
+ ### Resource Discovery
320
+
321
+ Tools are associated with UI resources through the `_meta.ui` field:
322
+
323
+ ```typescript
324
+ interface McpUiToolMeta {
325
+ /** URI of UI resource for rendering tool results */
326
+ resourceUri?: string;
327
+ /**
328
+ * Who can access this tool. Default: ["model", "app"]
329
+ * - "model": Tool visible to and callable by the agent
330
+ * - "app": Tool callable by the app from this server only
331
+ */
332
+ visibility?: Array<"model" | "app">;
333
+ }
334
+
335
+ interface Tool {
336
+ name: string;
337
+ description: string;
338
+ inputSchema: object;
339
+ _meta?: {
340
+ ui?: McpUiToolMeta;
341
+ /** @deprecated Use `ui.resourceUri` instead. Will be removed before GA. */
342
+ "ui/resourceUri"?: string;
343
+ };
344
+ }
345
+ ```
346
+
347
+ > **Deprecation notice:** The flat `_meta["ui/resourceUri"]` format is deprecated. Use `_meta.ui.resourceUri` instead. The deprecated format will be removed before GA.
348
+
349
+ Example (tool visible to both model and app):
350
+
351
+ ```json
352
+ {
353
+ "name": "get_weather",
354
+ "description": "Get current weather for a location",
355
+ "inputSchema": {
356
+ "type": "object",
357
+ "properties": {
358
+ "location": { "type": "string" }
359
+ }
360
+ },
361
+ "_meta": {
362
+ "ui": {
363
+ "resourceUri": "ui://weather-server/dashboard-template",
364
+ "visibility": ["model", "app"]
365
+ }
366
+ }
367
+ }
368
+ ```
369
+
370
+ Example (app-only tool, hidden from model):
371
+
372
+ ```json
373
+ {
374
+ "name": "refresh_dashboard",
375
+ "description": "Refresh dashboard data",
376
+ "inputSchema": { "type": "object" },
377
+ "_meta": {
378
+ "ui": {
379
+ "resourceUri": "ui://weather-server/dashboard-template",
380
+ "visibility": ["app"]
381
+ }
382
+ }
383
+ }
384
+ ```
385
+
386
+ #### Behavior:
387
+
388
+ - If `ui.resourceUri` is present and host supports MCP Apps, host renders tool results using the specified UI resource
389
+ - If host does not support MCP Apps, tool behaves as standard tool (text-only fallback)
390
+ - Resource MUST exist on the server
391
+ - Host MUST use `resources/read` to fetch the referenced resource URI
392
+ - Host MAY prefetch and cache UI resource content for performance optimization
393
+ - Since UI resources are primarily discovered through tool metadata, Servers MAY omit UI-only resources from `resources/list` and `notifications/resources/list_changed`
394
+
395
+ #### Visibility:
396
+
397
+ - `visibility` defaults to `["model", "app"]` if omitted
398
+ - `"model"`: Tool is visible to and callable by the agent
399
+ - `"app"`: Tool is callable by the app from the same server connection only
400
+ - **tools/list behavior:** Host MUST NOT include tools in the agent's tool list when their visibility does not include `"model"` (e.g., `visibility: ["app"]`)
401
+ - **tools/call behavior:** Host MUST reject `tools/call` requests from apps for tools that don't include `"app"` in visibility
402
+ - Cross-server tool calls are always blocked for app-only tools
403
+
404
+ #### Benefits:
405
+
406
+ - **Performance:** Host can preload templates before tool execution
407
+ - **Security:** Host can review UI templates during connection setup
408
+ - **Caching:** Separate template (static) from data (dynamic)
409
+ - **Auditability:** All UI resources are enumerable and inspectable
410
+
411
+ ### Communication Protocol
412
+
413
+ MCP Apps uses JSON-RPC 2.0 over `postMessage` for iframe-host communication. UI capabilities (e.g., tool call, prompt, etc.) will reuse MCP’s existing protocol. In the future, we may choose to enrich the communication protocol with additional MCP capabilities.
414
+
415
+ ### Transport Layer
416
+
417
+ The View connects to the Host via `postMessage`. The Apps handshake uses `ui/initialize` with `appInfo`, `appCapabilities`, and `protocolVersion`, followed by `ui/notifications/initialized`. The Host-to-Server handshake has its own [capability negotiation](#clientserver-capability-negotiation).
418
+
419
+ With `@modelcontextprotocol/ext-apps`, `App.connect()` handles the View handshake:
420
+
421
+ ```typescript
422
+ import { App } from "@modelcontextprotocol/ext-apps";
423
+
424
+ const app = new App(
425
+ { name: "My UI", version: "1.0.0" },
426
+ { availableDisplayModes: ["fullscreen"] },
427
+ );
428
+ await app.connect();
429
+ ```
430
+
431
+ The same handshake can be sent as JSON-RPC over `postMessage`:
432
+
433
+ ```typescript
434
+ let nextId = 1;
435
+ function sendRequest(method: string, params: Record<string, unknown>) {
436
+ const id = nextId++;
437
+ return new Promise<unknown>((resolve, reject) => {
438
+ function onResponse(event: MessageEvent) {
439
+ const response = event.data;
440
+ if (event.source !== window.parent || response?.jsonrpc !== "2.0" || response.id !== id) {
441
+ return;
442
+ }
443
+ if (response.error) {
444
+ window.removeEventListener("message", onResponse);
445
+ reject(new Error(response.error.message));
446
+ } else if ("result" in response) {
447
+ window.removeEventListener("message", onResponse);
448
+ resolve(response.result);
449
+ }
450
+ }
451
+ window.addEventListener("message", onResponse);
452
+ window.parent.postMessage({ jsonrpc: "2.0", id, method, params }, "*");
453
+ });
454
+ }
455
+ function sendNotification(method: string, params: Record<string, unknown>) {
456
+ window.parent.postMessage({ jsonrpc: "2.0", method, params }, "*");
457
+ }
458
+
459
+ const initializeResult = await sendRequest("ui/initialize", {
460
+ appCapabilities: { availableDisplayModes: ["fullscreen"] },
461
+ appInfo: { name: "My UI", version: "1.0.0" },
462
+ protocolVersion: "2026-01-26",
463
+ });
464
+ sendNotification("ui/notifications/initialized", {});
465
+ ```
466
+
467
+ Declare `appCapabilities.tools` only if the View exposes its own tools to the Host. The Host advertises support for proxying calls to server tools through `hostCapabilities.serverTools`.
468
+
469
+ Hosts act as MCP servers (that can proxy the actual MCP server), receiving and handling requests from UI iframes.
470
+
471
+ ### Sandbox proxy
472
+
473
+ If the Host is a web page, it MUST wrap the View and communicate with it through an intermediate Sandbox proxy.
474
+
475
+ 1. The Host and the Sandbox MUST have different origins.
476
+ 2. The Sandbox MUST have the following permissions: `allow-scripts`, `allow-same-origin`.
477
+ 3. The Sandbox MUST send a `ui/notifications/sandbox-proxy-ready` notification to the host when it's ready to process an `ui/notifications/sandbox-resource-ready` notification.
478
+ 4. Once the Sandbox is ready, the Host MUST send the raw HTML resource to load in a `ui/notifications/sandbox-resource-ready` notification.
479
+ 5. The Sandbox MUST load the raw HTML of the View with CSP settings that:
480
+ - Enforce the domains declared in `ui.csp` metadata
481
+ - If `frameDomains` is provided, allow nested iframes from declared origins; otherwise use `frame-src 'none'`
482
+ - If `baseUriDomains` is provided, allow base URIs from declared origins; otherwise use `base-uri 'self'`
483
+ - Block dangerous features (`object-src 'none'`)
484
+ - Apply restrictive defaults if no CSP metadata is provided
485
+ - If `permissions` is declared, the Sandbox MAY set the inner iframe's `allow` attribute accordingly
486
+ 6. The Sandbox MUST forward messages sent by the Host to the View, and vice versa, for any method that doesn't start with `ui/notifications/sandbox-`. This includes lifecycle messages, e.g., `ui/initialize` request & `ui/notifications/initialized` notification both sent by the View. The Host MUST NOT send any request or notification to the View before it receives an `initialized` notification.
487
+ 7. The Sandbox SHOULD NOT create/send any requests to the Host or to the View (this would require synthesizing new request ids).
488
+ 8. The Host MAY forward any message from the View (coming via the Sandbox) to the MCP Apps server, for any method that doesn't start with `ui/`. While the Host SHOULD ensure the View's MCP connection is spec-compliant, it MAY decide to block some messages or subject them to further user approval.
489
+
490
+ ### Standard MCP Messages
491
+
492
+ UI iframes can use the following subset of standard MCP protocol messages:
493
+
494
+ **Tools:**
495
+
496
+ - `tools/call` - Execute a tool on the MCP server
497
+
498
+ **Resources:**
499
+
500
+ - `resources/read` - Read resource content
501
+
502
+ **Notifications:**
503
+
504
+ - `notifications/message` - Log messages to host
505
+
506
+ **Lifecycle:**
507
+
508
+ - `ui/initialize` → `ui/notifications/initialized` - MCP-like handshake (replaces custom iframe-ready pattern in MCP-UI)
509
+ - `ping` - Connection health check
510
+
511
+ ### App Capabilities in `ui/initialize`
512
+
513
+ When the View sends an `ui/initialize` request to the Host, it MUST include its capabilities in the `appCapabilities` field:
514
+
515
+ ```typescript
516
+ interface McpUiAppCapabilities {
517
+ /** Experimental features keyed by identifier. */
518
+ experimental?: Record<string, object>;
519
+ /** App exposes MCP-style tools that the host can call. */
520
+ tools?: {
521
+ /** App supports tools/list_changed notifications. */
522
+ listChanged?: boolean;
523
+ };
524
+ /**
525
+ * Display modes the app supports. See Display Modes section for details.
526
+ * @example ["inline", "fullscreen"]
527
+ */
528
+ availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">;
529
+ }
530
+ ```
531
+
532
+ ### Host Context in `McpUiInitializeResult`
533
+
534
+ When the View sends an `ui/initialize` request to the Host, the Host SHOULD include UI-specific context in the `McpUiInitializeResult`'s `hostContext` field:
535
+
536
+ ```typescript
537
+ interface HostContext {
538
+ /** Metadata of the tool call that instantiated the View */
539
+ toolInfo?: {
540
+ /** JSON-RPC id of the tools/call request */
541
+ id?: RequestId,
542
+ /** Contains name, inputSchema, etc… */
543
+ tool: Tool,
544
+ };
545
+ /** Current color theme preference */
546
+ theme?: "light" | "dark";
547
+ /** Style configuration for theming. See Theming section for standardized variable names. */
548
+ styles?: {
549
+ /** CSS variables for theming */
550
+ variables?: Record<McpUiStyleVariableKey, string | undefined>;
551
+ /** CSS blocks that Views can inject */
552
+ css?: {
553
+ /** CSS for font loading (@font-face rules or @import statements) */
554
+ fonts?: string;
555
+ };
556
+ };
557
+ /** How the View is currently displayed */
558
+ displayMode?: "inline" | "fullscreen" | "pip";
559
+ /** Display modes the host supports */
560
+ availableDisplayModes?: string[];
561
+ /** Container dimensions for the iframe. Specify either width or maxWidth, and either height or maxHeight. */
562
+ containerDimensions?: (
563
+ | { height: number } // If specified, container is fixed at this height
564
+ | { maxHeight?: number } // Otherwise, container height is determined by the View's height, up to this maximum height (if defined)
565
+ ) & (
566
+ | { width: number } // If specified, container is fixed at this width
567
+ | { maxWidth?: number } // Otherwise, container width is determined by the View's width, up to this maximum width (if defined)
568
+ );
569
+ /** User's language/region preference (BCP 47, e.g., "en-US") */
570
+ locale?: string;
571
+ /** User's timezone (IANA, e.g., "America/New_York") */
572
+ timeZone?: string;
573
+ /** Host application identifier */
574
+ userAgent?: string;
575
+ /** Platform type for responsive design */
576
+ platform?: "web" | "desktop" | "mobile";
577
+ /** Device capabilities such as touch */
578
+ deviceCapabilities?: {
579
+ touch?: boolean;
580
+ hover?: boolean;
581
+ }
582
+ /** Safe area boundaries in pixels */
583
+ safeAreaInsets?: {
584
+ top: number;
585
+ right: number;
586
+ bottom: number;
587
+ left: number;
588
+ };
589
+ }
590
+ ```
591
+
592
+ Example:
593
+
594
+ ```json
595
+ // Host responds with McpUiInitializeResult
596
+ {
597
+ "jsonrpc": "2.0",
598
+ "id": 1,
599
+ "result": {
600
+ "protocolVersion": "2026-01-26",
601
+ "hostCapabilities": { /* ... */ },
602
+ "hostInfo": { "name": "claude-desktop", "version": "1.0.0" },
603
+ "hostContext": {
604
+ "theme": "dark",
605
+ "styles": {
606
+ "variables": {
607
+ "--color-background-primary": "light-dark(#ffffff, #171717)",
608
+ "--color-text-primary": "light-dark(#171717, #fafafa)",
609
+ "--font-sans": "Anthropic Sans, sans-serif",
610
+ ...
611
+ },
612
+ "css": {
613
+ "fonts": "@font-face { font-family: \"Custom Font Name\"; src: url(\"https://...\"); }"
614
+ }
615
+ },
616
+ "displayMode": "inline",
617
+ "containerDimensions": { "width": 400, "maxHeight": 600 }
618
+ }
619
+ }
620
+ }
621
+ ```
622
+
623
+ ### Host Capabilities
624
+
625
+ `hostCapabilities` in the `ui/initialize` result describes the features supplied by the current Host. The following shape follows `@modelcontextprotocol/ext-apps@^1.7.5`. The View checks the advertised capability before using its associated feature.
626
+
627
+ ```typescript
628
+ interface McpUiSupportedContentBlockModalities {
629
+ text?: {};
630
+ image?: {};
631
+ audio?: {};
632
+ resource?: {};
633
+ resourceLink?: {};
634
+ structuredContent?: {};
635
+ }
636
+
637
+ interface HostCapabilities {
638
+ /** Experimental features keyed by identifier. */
639
+ experimental?: Record<string, object>;
640
+ /** Host supports opening external URLs. */
641
+ openLinks?: {};
642
+ /** Host supports file downloads via ui/download-file. */
643
+ downloadFile?: {};
644
+ /** Host can proxy tool calls to the MCP server. */
645
+ serverTools?: {
646
+ /** Host supports tools/list_changed notifications. */
647
+ listChanged?: boolean;
648
+ };
649
+ /** Host can proxy resource reads to the MCP server. */
650
+ serverResources?: {
651
+ /** Host supports resources/list_changed notifications. */
652
+ listChanged?: boolean;
653
+ };
654
+ /** Host accepts log messages. */
655
+ logging?: {};
656
+ /** Host supports these content types in ui/message. */
657
+ message?: McpUiSupportedContentBlockModalities;
658
+ /** Host supports these content types in ui/update-model-context. */
659
+ updateModelContext?: McpUiSupportedContentBlockModalities;
660
+ /** Host accepts sampling/createMessage requests from the View. */
661
+ sampling?: {
662
+ /** Host supports tools and toolChoice in sampling requests. */
663
+ tools?: {};
664
+ };
665
+ /** Sandbox configuration applied by the host. */
666
+ sandbox?: {
667
+ /** Permissions granted by the host (camera, microphone, geolocation, clipboard-write). */
668
+ permissions?: {
669
+ camera?: {};
670
+ microphone?: {};
671
+ geolocation?: {};
672
+ clipboardWrite?: {};
673
+ };
674
+ /** CSP domains approved by the host. */
675
+ csp?: {
676
+ /** Approved origins for network requests (fetch/XHR/WebSocket). */
677
+ connectDomains?: string[];
678
+ /** Approved origins for static resources (scripts, images, styles, fonts). */
679
+ resourceDomains?: string[];
680
+ /** Approved origins for nested iframes (frame-src directive). */
681
+ frameDomains?: string[];
682
+ /** Approved base URIs for the document (base-uri directive). */
683
+ baseUriDomains?: string[];
684
+ };
685
+ };
686
+ }
687
+ ```
688
+
689
+ ### Container Dimensions
690
+
691
+ The `HostContext` provides sizing information via `containerDimensions`:
692
+
693
+ - **`containerDimensions`**: The dimensions of the container that holds the View. This controls the actual space the View occupies within the host. Each dimension (height and width) operates independently and can be either **fixed** or **flexible**.
694
+
695
+ #### Dimension Modes
696
+
697
+ | Mode | Dimensions Field | Meaning |
698
+ |------|-----------------|---------|
699
+ | Fixed | `height` or `width` | Host controls the size. View should fill the available space. |
700
+ | Flexible | `maxHeight` or `maxWidth` | View controls the size, up to the specified maximum. |
701
+ | Unbounded | Field omitted | View controls the size with no limit. |
702
+
703
+ These modes can be combined independently. For example, a host might specify a fixed width but flexible height, allowing the View to grow vertically based on content.
704
+
705
+ #### View Behavior
706
+
707
+ Views should check the containerDimensions configuration and apply appropriate CSS:
708
+
709
+ ```typescript
710
+ // In the View's initialization
711
+ const containerDimensions = hostContext.containerDimensions;
712
+
713
+ if (containerDimensions) {
714
+ // Handle height
715
+ if ("height" in containerDimensions) {
716
+ // Fixed height: fill the container
717
+ document.documentElement.style.height = "100vh";
718
+ } else if ("maxHeight" in containerDimensions && containerDimensions.maxHeight) {
719
+ // Flexible with max: let content determine size, up to max
720
+ document.documentElement.style.maxHeight = `${containerDimensions.maxHeight}px`;
721
+ }
722
+ // If neither, height is unbounded
723
+
724
+ // Handle width
725
+ if ("width" in containerDimensions) {
726
+ // Fixed width: fill the container
727
+ document.documentElement.style.width = "100vw";
728
+ } else if ("maxWidth" in containerDimensions && containerDimensions.maxWidth) {
729
+ // Flexible with max: let content determine size, up to max
730
+ document.documentElement.style.maxWidth = `${containerDimensions.maxWidth}px`;
731
+ }
732
+ // If neither, width is unbounded
733
+ }
734
+ ```
735
+
736
+ #### Host Behavior
737
+
738
+ When using flexible dimensions (no fixed `height` or `width`), hosts MUST listen for `ui/notifications/size-changed` notifications from the View and update the iframe dimensions accordingly:
739
+
740
+ ```typescript
741
+ // Host listens for size changes from the View
742
+ bridge.onsizechange = ({ width, height }) => {
743
+ // Update iframe to match View's content size
744
+ if (width != null) {
745
+ iframe.style.width = `${width}px`;
746
+ }
747
+ if (height != null) {
748
+ iframe.style.height = `${height}px`;
749
+ }
750
+ };
751
+ ```
752
+
753
+ Views using the SDK automatically send size-changed notifications via ResizeObserver when `autoResize` is enabled (the default). The notifications are debounced and only sent when dimensions actually change.
754
+
755
+ ### Display Modes
756
+
757
+ Views can be displayed in different modes depending on the host's capabilities and the view's declared support.
758
+
759
+ ```typescript
760
+ type McpUiDisplayMode = "inline" | "fullscreen" | "pip";
761
+ ```
762
+
763
+ - **inline**: Default mode, embedded within the host's content flow
764
+ - **fullscreen**: View takes over the full screen/window
765
+ - **pip**: Picture-in-picture, floating overlay
766
+
767
+ #### Declaring Support
768
+
769
+ **View (`appCapabilities.availableDisplayModes`):**
770
+
771
+ Views declare which display modes they support in the `ui/initialize` request via `appCapabilities.availableDisplayModes`. This allows hosts to only offer display mode options that the view can handle.
772
+
773
+ ```typescript
774
+ // Example: View declares support for inline and fullscreen
775
+ {
776
+ method: "ui/initialize",
777
+ params: {
778
+ appCapabilities: {
779
+ availableDisplayModes: ["inline", "fullscreen"]
780
+ },
781
+ // ...
782
+ }
783
+ }
784
+ ```
785
+
786
+ **Host (`HostContext.availableDisplayModes`):**
787
+
788
+ Hosts declare which display modes they support in `HostContext.availableDisplayModes`. Views should check this before requesting a mode change.
789
+
790
+ #### Requesting Changes
791
+
792
+ Views request display mode changes via `ui/request-display-mode`. See the Requests section for message format.
793
+
794
+ #### Notifying Changes
795
+
796
+ Hosts notify views of display mode changes via `ui/notifications/host-context-changed` with the `displayMode` field.
797
+
798
+ #### Requirements
799
+
800
+ **View behavior:**
801
+ - View MUST declare all display modes it supports in `appCapabilities.availableDisplayModes` during initialization.
802
+ - View MUST check if the requested mode is in `availableDisplayModes` from host context before requesting a mode change.
803
+ - View MUST handle the response mode differing from the requested mode.
804
+
805
+ **Host behavior:**
806
+ - Host MUST NOT switch the View to a display mode that does not appear in its `appCapabilities.availableDisplayModes`, if set.
807
+ - Host MUST return the resulting mode (whether updated or not) in the response to `ui/request-display-mode`.
808
+ - If the requested mode is not available, Host SHOULD return the current display mode in the response.
809
+ - Host MAY decline display mode requests from Views that did not declare said modes in their capabilities.
810
+
811
+ ### Theming
812
+
813
+ Hosts can optionally pass CSS custom properties via `HostContext.styles.variables` for visual cohesion with the host environment.
814
+
815
+ #### Current Standardized Variables
816
+
817
+ ```typescript
818
+ /** CSS variable keys available to Views for theming. */
819
+ type McpUiStyleVariableKey =
820
+ // Background colors
821
+ | "--color-background-primary"
822
+ | "--color-background-secondary"
823
+ | "--color-background-tertiary"
824
+ | "--color-background-inverse"
825
+ | "--color-background-ghost"
826
+ | "--color-background-info"
827
+ | "--color-background-danger"
828
+ | "--color-background-success"
829
+ | "--color-background-warning"
830
+ | "--color-background-disabled"
831
+ // Text colors
832
+ | "--color-text-primary"
833
+ | "--color-text-secondary"
834
+ | "--color-text-tertiary"
835
+ | "--color-text-inverse"
836
+ | "--color-text-info"
837
+ | "--color-text-danger"
838
+ | "--color-text-success"
839
+ | "--color-text-warning"
840
+ | "--color-text-disabled"
841
+ | "--color-text-ghost"
842
+ // Border colors
843
+ | "--color-border-primary"
844
+ | "--color-border-secondary"
845
+ | "--color-border-tertiary"
846
+ | "--color-border-inverse"
847
+ | "--color-border-ghost"
848
+ | "--color-border-info"
849
+ | "--color-border-danger"
850
+ | "--color-border-success"
851
+ | "--color-border-warning"
852
+ | "--color-border-disabled"
853
+ // Ring colors
854
+ | "--color-ring-primary"
855
+ | "--color-ring-secondary"
856
+ | "--color-ring-inverse"
857
+ | "--color-ring-info"
858
+ | "--color-ring-danger"
859
+ | "--color-ring-success"
860
+ | "--color-ring-warning"
861
+ // Typography - Family
862
+ | "--font-sans"
863
+ | "--font-mono"
864
+ // Typography - Weight
865
+ | "--font-weight-normal"
866
+ | "--font-weight-medium"
867
+ | "--font-weight-semibold"
868
+ | "--font-weight-bold"
869
+ // Typography - Text Size
870
+ | "--font-text-xs-size"
871
+ | "--font-text-sm-size"
872
+ | "--font-text-md-size"
873
+ | "--font-text-lg-size"
874
+ // Typography - Heading Size
875
+ | "--font-heading-xs-size"
876
+ | "--font-heading-sm-size"
877
+ | "--font-heading-md-size"
878
+ | "--font-heading-lg-size"
879
+ | "--font-heading-xl-size"
880
+ | "--font-heading-2xl-size"
881
+ | "--font-heading-3xl-size"
882
+ // Typography - Text Line Height
883
+ | "--font-text-xs-line-height"
884
+ | "--font-text-sm-line-height"
885
+ | "--font-text-md-line-height"
886
+ | "--font-text-lg-line-height"
887
+ // Typography - Heading Line Height
888
+ | "--font-heading-xs-line-height"
889
+ | "--font-heading-sm-line-height"
890
+ | "--font-heading-md-line-height"
891
+ | "--font-heading-lg-line-height"
892
+ | "--font-heading-xl-line-height"
893
+ | "--font-heading-2xl-line-height"
894
+ | "--font-heading-3xl-line-height"
895
+ // Border radius
896
+ | "--border-radius-xs"
897
+ | "--border-radius-sm"
898
+ | "--border-radius-md"
899
+ | "--border-radius-lg"
900
+ | "--border-radius-xl"
901
+ | "--border-radius-full"
902
+ // Border width
903
+ | "--border-width-regular"
904
+ // Shadows
905
+ | "--shadow-hairline"
906
+ | "--shadow-sm"
907
+ | "--shadow-md"
908
+ | "--shadow-lg";
909
+ ```
910
+
911
+ #### Host Behavior
912
+
913
+ - Hosts can provide any subset of standardized variables, or not pass `styles` at all
914
+ - However, unexpected clashes may occur if hosts pass some color variables but not others for example, since Views are instructed to fallback on their own default values for unspecified style variables
915
+ - Hosts should use the CSS `light-dark()` function for theme-aware values (i.e. light mode and dark mode colors)
916
+
917
+ #### View Behavior
918
+
919
+ - Views should set default fallback values for the set of these variables that they use, to account for hosts who don't pass some or all style variables. This ensures graceful degradation when hosts omit `styles` or specific variables:
920
+ ```
921
+ :root {
922
+ --color-text-primary: light-dark(#171717, #000000);
923
+ --border-radius-small: 8px;
924
+ ...
925
+ }
926
+ ```
927
+ - Views can use the `applyHostStyleVariables` utility (or `useHostStyleVariables` if they prefer a React hook) to easily populate the host-provided CSS variables into their style sheet
928
+ - Views can use the `applyDocumentTheme` utility (or `useDocumentTheme` if they prefer a React hook) to easily respond to Host Context `theme` changes in a way that is compatible with the host's light/dark color variables
929
+
930
+ Example usage of standardized CSS variables:
931
+
932
+ ```css
933
+ .container {
934
+ background: var(--color-background-primary);
935
+ color: var(--color-text-primary);
936
+ font-family: var(--font-sans);
937
+ }
938
+ ```
939
+
940
+ #### Custom Fonts
941
+
942
+ Hosts can provide custom fonts via `styles.css.fonts`, which can contain `@font-face` rules for self-hosted fonts, `@import` statements for font services like Google Fonts, or both:
943
+
944
+ ```typescript
945
+ hostContext.styles.variables["--font-sans"] = '"Font Name", sans-serif';
946
+
947
+ // Self-hosted fonts
948
+ hostContext.styles.css.fonts = `
949
+ @font-face {
950
+ font-family: "Font Name";
951
+ src: url("https://url-where-font-is-hosted.com/.../Regular.otf") format("opentype");
952
+ font-weight: 400;
953
+ font-style: normal;
954
+ font-display: swap;
955
+ }
956
+ @font-face {
957
+ font-family: "Font Name";
958
+ src: url("https://url-where-font-is-hosted.com/.../Medium.otf") format("opentype");
959
+ font-weight: 500;
960
+ font-style: medium;
961
+ font-display: swap;
962
+ }
963
+ `;
964
+
965
+ // Google Fonts
966
+ hostContext.styles.css.fonts = `
967
+ @import url('https://fonts.googleapis.com/css2?family=Font+Name&display=swap');
968
+ `;
969
+ ```
970
+
971
+ Views can use the `applyHostFonts` utility to inject the font CSS into the document:
972
+
973
+ ```typescript
974
+ if (hostContext.styles?.css?.fonts) {
975
+ applyHostFonts(hostContext.styles.css.fonts);
976
+ }
977
+ ```
978
+
979
+ ### MCP Apps Specific Messages
980
+
981
+ MCP Apps introduces additional JSON-RPC methods for UI-specific functionality:
982
+
983
+ #### Requests (View → Host)
984
+
985
+ `ui/open-link` - Request host to open external URL
986
+
987
+ ```typescript
988
+ // Request
989
+ {
990
+ jsonrpc: "2.0",
991
+ id: 1,
992
+ method: "ui/open-link",
993
+ params: {
994
+ url: string // URL to open in host's browser
995
+ }
996
+ }
997
+
998
+ // Success Response
999
+ {
1000
+ jsonrpc: "2.0",
1001
+ id: 1,
1002
+ result: {} // Empty result on success
1003
+ }
1004
+
1005
+ // Error Response (if denied or failed)
1006
+ {
1007
+ jsonrpc: "2.0",
1008
+ id: 1,
1009
+ error: {
1010
+ code: -32000, // Implementation-defined error
1011
+ message: "Link opening denied by user" | "Invalid URL" | "Policy violation"
1012
+ }
1013
+ }
1014
+ ```
1015
+
1016
+ Host SHOULD open the URL in the user's default browser or a new tab.
1017
+
1018
+ `ui/download-file` - Request a file download through the Host
1019
+
1020
+ The View checks `hostCapabilities.downloadFile` before sending this request. The SDK's `App.downloadFile()` takes `{ contents: (EmbeddedResource | ResourceLink)[] }`. The response can include `isError: true` if the download fails or is declined.
1021
+
1022
+ `ui/message` - Send message content to the host's chat interface
1023
+
1024
+ ```json
1025
+ {
1026
+ "jsonrpc": "2.0",
1027
+ "id": 2,
1028
+ "method": "ui/message",
1029
+ "params": {
1030
+ "role": "user",
1031
+ "content": [{ "type": "text", "text": "Show the latest report." }]
1032
+ }
1033
+ }
1034
+ ```
1035
+
1036
+ The response's `result` can be `{}` on success or `{ "isError": true }` if the Host rejected or failed to deliver the message.
1037
+
1038
+ The Host SHOULD add the message to the conversation context, preserving the specified role. The Host MAY request user consent.
1039
+
1040
+ `ui/request-display-mode` - Request host to change display mode
1041
+
1042
+ ```typescript
1043
+ // Request
1044
+ {
1045
+ jsonrpc: "2.0",
1046
+ id: 3,
1047
+ method: "ui/request-display-mode",
1048
+ params: {
1049
+ mode: "inline" | "fullscreen" | "pip" // Requested display mode
1050
+ }
1051
+ }
1052
+
1053
+ // Success Response
1054
+ {
1055
+ jsonrpc: "2.0",
1056
+ id: 3,
1057
+ result: {
1058
+ mode: "inline" | "fullscreen" | "pip" // Actual display mode set
1059
+ }
1060
+ }
1061
+ ```
1062
+
1063
+ See the Display Modes section for detailed behavior requirements.
1064
+
1065
+ `ui/update-model-context` - Update the model context
1066
+
1067
+ ```typescript
1068
+ // Request
1069
+ {
1070
+ jsonrpc: "2.0",
1071
+ id: 3,
1072
+ method: "ui/update-model-context",
1073
+ params: {
1074
+ content?: ContentBlock[],
1075
+ structuredContent?: Record<string, unknown>
1076
+ }
1077
+ }
1078
+
1079
+ // Success Response
1080
+ {
1081
+ jsonrpc: "2.0",
1082
+ id: 3,
1083
+ result: {} // Empty result on success
1084
+ }
1085
+
1086
+ // Error Response (if denied or failed)
1087
+ {
1088
+ jsonrpc: "2.0",
1089
+ id: 3,
1090
+ error: {
1091
+ code: -32000, // Implementation-defined error
1092
+ message: "Context update denied" | "Invalid content format"
1093
+ }
1094
+ }
1095
+ ```
1096
+
1097
+ The View MAY send this request to update the Host's model context. This context will be used in future turns. Each request overwrites the previous context sent by the View.
1098
+ This event serves a different use case from `notifications/message` (logging) and `ui/message` (which also trigger follow-ups).
1099
+
1100
+ Host behavior:
1101
+ - SHOULD provide the context to the model in future turns
1102
+ - MAY overwrite the previous model context with the new update
1103
+ - MAY defer sending the context to the model until the next user message (including `ui/message`)
1104
+ - MAY dedupe identical `ui/update-model-context` calls
1105
+ - If multiple updates are received before the next user message, Host SHOULD only send the last update to the model
1106
+ - MAY display context updates to the user
1107
+
1108
+ #### Notifications (Host → View)
1109
+
1110
+ `ui/notifications/tool-input` - Deliver the tool's complete input
1111
+
1112
+ ```json
1113
+ {
1114
+ "jsonrpc": "2.0",
1115
+ "method": "ui/notifications/tool-input",
1116
+ "params": { "arguments": { "location": "San Francisco" } }
1117
+ }
1118
+ ```
1119
+
1120
+ Host sends this notification after receiving `ui/notifications/initialized`, when the tool input becomes available. This notification is sent at most once and is required before sending `ui/notifications/tool-result`. The SDK accepts `params: {}` when the tool call supplies no arguments.
1121
+
1122
+ `ui/notifications/tool-input-partial` - Host MAY send this notification zero or more times while the agent is streaming tool arguments, before `ui/notifications/tool-input` is sent.
1123
+
1124
+ ```json
1125
+ {
1126
+ "jsonrpc": "2.0",
1127
+ "method": "ui/notifications/tool-input-partial",
1128
+ "params": { "arguments": { "location": "San" } }
1129
+ }
1130
+ ```
1131
+
1132
+ The optional `params.arguments` object represents best-effort recovery of incomplete JSON, with unclosed structures automatically closed to produce valid JSON. Host behavior (optional):
1133
+
1134
+ - MAY parse the agent's partial JSON output by closing unclosed brackets/braces
1135
+ - MAY send recovered arguments as they become available during streaming
1136
+ - MUST stop sending once `ui/notifications/tool-input` is sent with complete arguments
1137
+
1138
+ View behavior (optional):
1139
+
1140
+ - MAY ignore these notifications entirely
1141
+ - MAY render progressive loading/streaming states based on available fields
1142
+ - MUST NOT rely on partial arguments for critical operations
1143
+ - SHOULD gracefully handle missing or changing fields between notifications
1144
+
1145
+ `ui/notifications/tool-result` - Tool execution result
1146
+
1147
+ ```typescript
1148
+ {
1149
+ jsonrpc: "2.0",
1150
+ method: "ui/notifications/tool-result",
1151
+ params: CallToolResult // Standard MCP type
1152
+ }
1153
+ ```
1154
+
1155
+ Host MUST send this notification when tool execution completes (if the View is displayed during tool execution).
1156
+
1157
+ `ui/notifications/tool-cancelled` - Tool execution was cancelled
1158
+
1159
+ ```json
1160
+ {
1161
+ "jsonrpc": "2.0",
1162
+ "method": "ui/notifications/tool-cancelled",
1163
+ "params": { "reason": "user cancelled" }
1164
+ }
1165
+ ```
1166
+
1167
+ Host MUST send this notification if the tool execution was cancelled. The optional `params.reason` can describe the cancellation.
1168
+
1169
+ `ui/notifications/host-context-changed` - Host context has changed
1170
+
1171
+ ```typescript
1172
+ {
1173
+ jsonrpc: "2.0",
1174
+ method: "ui/notifications/host-context-changed",
1175
+ params: Partial<HostContext> // See HostContext type above
1176
+ }
1177
+ ```
1178
+
1179
+ Host MAY send this notification when any context field changes (e.g., theme toggle, display mode change, device orientation change, window/panel resize). This notification contains partial updates - the View SHOULD merge received fields with its current context state.
1180
+
1181
+ #### Requests (Host → View)
1182
+
1183
+ `ui/resource-teardown` - Request graceful shutdown of the View
1184
+
1185
+ ```json
1186
+ {
1187
+ "jsonrpc": "2.0",
1188
+ "id": 1,
1189
+ "method": "ui/resource-teardown",
1190
+ "params": {}
1191
+ }
1192
+ ```
1193
+
1194
+ Host MUST send this request with an empty parameter object before tearing down the UI resource. The View returns an empty result on success or a JSON-RPC error on failure. Host SHOULD wait for a response before tearing down the resource to prevent data loss.
1195
+
1196
+ #### Notifications (View → Host)
1197
+
1198
+ `ui/notifications/size-changed` - View's size changed
1199
+
1200
+ ```json
1201
+ {
1202
+ "jsonrpc": "2.0",
1203
+ "method": "ui/notifications/size-changed",
1204
+ "params": { "width": 640, "height": 400 }
1205
+ }
1206
+ ```
1207
+
1208
+ The View SHOULD send this notification when its rendered content size changes, for example using the ResizeObserver API. Each dimension is optional and expressed in pixels.
1209
+
1210
+ `ui/notifications/request-teardown` - Ask the Host to close the View
1211
+
1212
+ ```json
1213
+ {
1214
+ "jsonrpc": "2.0",
1215
+ "method": "ui/notifications/request-teardown"
1216
+ }
1217
+ ```
1218
+
1219
+ In SDK v1.7.5, `App.requestTeardown()` sends this notification. It has no reply. If the Host decides to close the View, it sends `ui/resource-teardown` to allow the View to clean up.
1220
+
1221
+ #### Reserved Messages (Sandbox Proxy)
1222
+
1223
+ These messages are reserved for web-based hosts that implement the recommended double-iframe sandbox architecture:
1224
+
1225
+ `ui/notifications/sandbox-proxy-ready` (Sandbox Proxy → Host) - Sandbox proxy is ready
1226
+
1227
+ ```typescript
1228
+ {
1229
+ jsonrpc: "2.0",
1230
+ method: "ui/notifications/sandbox-proxy-ready",
1231
+ params: {}
1232
+ }
1233
+ ```
1234
+
1235
+ `ui/notifications/sandbox-resource-ready` (Host → Sandbox Proxy) - HTML resource ready to load
1236
+
1237
+ ```typescript
1238
+ {
1239
+ jsonrpc: "2.0",
1240
+ method: "ui/notifications/sandbox-resource-ready",
1241
+ params: {
1242
+ html: string, // HTML content to load
1243
+ sandbox?: string, // Optional override for inner iframe `sandbox` attribute
1244
+ csp?: { // CSP configuration from resource metadata
1245
+ connectDomains?: string[],
1246
+ resourceDomains?: string[],
1247
+ frameDomains?: string[],
1248
+ baseUriDomains?: string[],
1249
+ },
1250
+ permissions?: { // Sandbox permissions from resource metadata
1251
+ camera?: {},
1252
+ microphone?: {},
1253
+ geolocation?: {},
1254
+ clipboardWrite?: {},
1255
+ }
1256
+ }
1257
+ }
1258
+ ```
1259
+
1260
+ These messages facilitate the communication between the outer sandbox proxy iframe and the host, enabling secure loading of untrusted HTML content. The `permissions` field maps to the inner iframe's `allow` attribute for Permission Policy features.
1261
+
1262
+ ### Lifecycle
1263
+
1264
+ The typical lifecycle for rendering a UI resource:
1265
+
1266
+ #### 1. Connection & Discovery
1267
+
1268
+ ```mermaid
1269
+ sequenceDiagram
1270
+ participant H as Host
1271
+ participant S as MCP Server
1272
+
1273
+ autonumber
1274
+ S -->> H: resources/list (includes ui:// resources)
1275
+ S -->> H: tools/list (includes tools with _meta.ui metadata)
1276
+ ```
1277
+
1278
+ #### 2. UI Initialization (Desktop/Native Hosts)
1279
+
1280
+ ```mermaid
1281
+ sequenceDiagram
1282
+ participant H as Host
1283
+ participant UI as View (iframe)
1284
+ participant P as Sandbox Proxy
1285
+ participant S as MCP Server
1286
+
1287
+ autonumber
1288
+ par UI Tool call
1289
+ H ->> S: tools/call to Tool with _meta.ui metadata
1290
+ and UI initialization
1291
+ alt Desktop/Native hosts
1292
+ H ->> H: Render View in an iframe (HTML from the ui:// resource)
1293
+ else Web hosts
1294
+ H ->> H: Render Sandbox Proxy in an iframe (different origin)
1295
+ P ->> H: ui/notifications/sandbox-proxy-ready
1296
+ H -->> P: ui/notifications/sandbox-resource-ready (HTML content)
1297
+ P -> P: Render inner iframe with HTML
1298
+
1299
+ end
1300
+ UI ->> H: ui/initialize
1301
+ H -->> UI: McpUiInitializeResult (e.g., host-context, capabilities, etc.)
1302
+ UI ->> H: ui/notifications/initialized
1303
+ opt Stream Tool input to UI
1304
+ H -->> UI: ui/notifications/tool-input-partial (0..n)
1305
+ end
1306
+ H -->> UI: ui/notifications/tool-input (complete)
1307
+ end
1308
+ alt Tool complete
1309
+ H -->> UI: ui/notifications/tool-result
1310
+ else Tool cancelled
1311
+ H -->> UI: ui/notifications/tool-cancelled
1312
+ end
1313
+ ```
1314
+
1315
+ Note: when the View is rendered inside a sandbox, the sandbox transparently passes messages between the View and the Host, except for messages named `ui/notifications/sandbox-*`.
1316
+
1317
+ #### 3. Interactive Phase
1318
+
1319
+ ```mermaid
1320
+ sequenceDiagram
1321
+ actor U as User / Agent
1322
+ participant H as Host
1323
+ participant UI as View (iframe)
1324
+ participant S as MCP Server
1325
+ loop Interactive phase
1326
+ U ->> UI: interaction (e.g., click)
1327
+ alt Tool call
1328
+ UI ->> H: tools/call
1329
+ H ->> S: tools/call
1330
+ opt Stream Tool input to UI
1331
+ H -->> UI: ui/notifications/tool-input-partial (0..n)
1332
+ end
1333
+ H -->> UI: ui/notifications/tool-input (complete)
1334
+ H-->>UI: ui/notifications/tool-result
1335
+ else Message
1336
+ UI ->> H: ui/message
1337
+ H -->> UI: ui/message response
1338
+ H -->> H: Process message and follow up
1339
+ else Context update
1340
+ UI ->> H: ui/update-model-context
1341
+ H ->> H: Store model context (overwrite existing)
1342
+ H -->> UI: ui/update-model-context response
1343
+ else Log
1344
+ UI ->> H: notifications/message
1345
+ H ->> H: Record log for debugging/telemetry
1346
+ else Resource read
1347
+ UI ->> H: resources/read
1348
+ H ->> S: resources/read
1349
+ S --> H: resources/read response
1350
+ H --> UI: resources/read response
1351
+ end
1352
+ opt View notifications
1353
+ UI ->> H: notifications (e.g., ui/notifications/size-changed)
1354
+ end
1355
+ opt Host notifications
1356
+ H ->> UI: notifications (e.g., ui/notifications/host-context-changed)
1357
+ end
1358
+ end
1359
+ ```
1360
+
1361
+ #### 4. Cleanup
1362
+
1363
+ ```mermaid
1364
+ sequenceDiagram
1365
+ participant H as Host
1366
+ participant UI as View (iframe)
1367
+ H ->> UI: ui/resource-teardown
1368
+ UI --> UI: Graceful termination
1369
+ UI -->> H: ui/resource-teardown response
1370
+ H -x H: Tear down iframe and listeners
1371
+ ```
1372
+
1373
+ Note: Cleanup may be triggered at any point in the lifecycle following View initialization.
1374
+
1375
+ #### Key Differences from Pre-SEP MCP-UI:
1376
+
1377
+ - Handshakes using MCP-like `ui/initialize` / `ui/notifications/initialized` messages instead of `iframe-ready`
1378
+ - Capabilities negotiated via `McpUiInitializeResult`
1379
+ - Tool data passed via notifications
1380
+
1381
+ ### Data Passing
1382
+
1383
+ Tool execution results are passed to the View through two mechanisms:
1384
+
1385
+ #### 1. Tool Input (via `ui/notifications/tool-input` notification)
1386
+
1387
+ The original tool call arguments:
1388
+
1389
+ ```typescript
1390
+ // Tool was called with (JSON-RPC request from Host to Server):
1391
+ {
1392
+ jsonrpc: "2.0",
1393
+ id: 1,
1394
+ method: "tools/call",
1395
+ params: {
1396
+ name: "get_weather",
1397
+ arguments: {
1398
+ location: "San Francisco"
1399
+ }
1400
+ }
1401
+ }
1402
+
1403
+ // View receives (JSON-RPC notification from Host to View):
1404
+ {
1405
+ jsonrpc: "2.0",
1406
+ method: "ui/notifications/tool-input",
1407
+ params: {
1408
+ arguments: {
1409
+ location: "San Francisco"
1410
+ }
1411
+ }
1412
+ }
1413
+ ```
1414
+
1415
+ #### 2. Tool Result (via `ui/notifications/tool-result` notification)
1416
+
1417
+ The tool's execution result:
1418
+
1419
+ ```typescript
1420
+ // Server returns from tool execution (JSON-RPC response):
1421
+ {
1422
+ jsonrpc: "2.0",
1423
+ id: 1, // Matches the tools/call request id
1424
+ result: {
1425
+ content: [
1426
+ { type: "text", text: "Current weather: Sunny, 72°F" }
1427
+ ],
1428
+ structuredContent: {
1429
+ temperature: 72,
1430
+ conditions: "sunny",
1431
+ humidity: 45
1432
+ },
1433
+ _meta: {
1434
+ timestamp: "2025-11-10T15:30:00Z",
1435
+ source: "weather-api"
1436
+ }
1437
+ }
1438
+ }
1439
+
1440
+ // View receives (JSON-RPC notification):
1441
+ {
1442
+ jsonrpc: "2.0",
1443
+ method: "ui/notifications/tool-result",
1444
+ params: {
1445
+ content: [
1446
+ { type: "text", text: "Current weather: Sunny, 72°F" }
1447
+ ],
1448
+ structuredContent: {
1449
+ temperature: 72,
1450
+ conditions: "sunny",
1451
+ humidity: 45
1452
+ },
1453
+ _meta: {
1454
+ timestamp: "2025-11-10T15:30:00Z",
1455
+ source: "weather-api"
1456
+ }
1457
+ }
1458
+ }
1459
+ ```
1460
+
1461
+ **Best Practices:**
1462
+
1463
+ - `content`: Text representation for model context and text-only hosts
1464
+ - `structuredContent`: Structured data optimized for UI rendering (not added to model context)
1465
+ - `_meta`: Additional metadata (timestamps, version info, etc.) not intended for model context
1466
+
1467
+ #### 3. Interactive Updates
1468
+
1469
+ Views can request fresh data by calling tools:
1470
+
1471
+ ```typescript
1472
+ // View requests updated data
1473
+ await client.callTool("get_weather", { location: "New York" });
1474
+
1475
+ // Result returned via standard tools/call response
1476
+ ```
1477
+
1478
+ This pattern enables interactive, self-updating views.
1479
+
1480
+ Note: Tools with `visibility: ["app"]` are hidden from the agent but remain callable by apps via `tools/call`. This enables UI-only interactions (refresh buttons, form submissions) without exposing implementation details to the model. See the Visibility section under Resource Discovery for details.
1481
+
1482
+ ### Client\<\>Server Capability Negotiation
1483
+
1484
+ Clients and servers negotiate MCP Apps support through the standard MCP extensions capability mechanism (defined in SEP-1724).
1485
+
1486
+ #### Client (Host) Capabilities
1487
+
1488
+ Clients advertise MCP Apps support in the initialize request using the extension identifier `io.modelcontextprotocol/ui`:
1489
+
1490
+ ```json
1491
+ {
1492
+ "method": "initialize",
1493
+ "params": {
1494
+ "protocolVersion": "2024-11-05",
1495
+ "capabilities": {
1496
+ "extensions": {
1497
+ "io.modelcontextprotocol/ui": {
1498
+ "mimeTypes": ["text/html;profile=mcp-app"]
1499
+ }
1500
+ }
1501
+ },
1502
+ "clientInfo": {
1503
+ "name": "claude-desktop",
1504
+ "version": "1.0.0"
1505
+ }
1506
+ }
1507
+ }
1508
+ ```
1509
+
1510
+ **Extension Settings:**
1511
+
1512
+ - `mimeTypes`: Array of supported content types (REQUIRED, e.g., `["text/html;profile=mcp-app"]`)
1513
+
1514
+ Future versions may add additional settings:
1515
+
1516
+ - `features`: Specific feature support (e.g., `["streaming", "persistence"]`)
1517
+ - `sandboxPolicies`: Supported sandbox attribute configurations
1518
+
1519
+ #### Server Behavior
1520
+
1521
+ Register the tool before connecting the server transport. After the MCP client initializes, check its capabilities and add UI metadata when it advertises the Apps MIME type. Register the dashboard resource at `ui://weather-server/dashboard` before connecting. If the server already has an `oninitialized` handler, add the metadata update to that handler.
1522
+
1523
+ ```typescript
1524
+ import { getUiCapability, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
1525
+ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
1526
+ import { z } from "zod";
1527
+
1528
+ function registerWeatherTool(server: McpServer, getWeather: (location: string) => Promise<string>) {
1529
+ const inputSchema = z.object({ location: z.string() });
1530
+ const tool = server.registerTool("get_weather", {
1531
+ description: "Get current weather",
1532
+ inputSchema,
1533
+ }, async ({ location }) => ({
1534
+ content: [{ type: "text" as const, text: await getWeather(location) }]
1535
+ }));
1536
+
1537
+ server.server.oninitialized = () => {
1538
+ const ui = getUiCapability(server.server.getClientCapabilities());
1539
+ tool.update({
1540
+ _meta: ui?.mimeTypes?.includes(RESOURCE_MIME_TYPE)
1541
+ ? { ui: { resourceUri: "ui://weather-server/dashboard" } }
1542
+ : {}
1543
+ });
1544
+ };
1545
+ }
1546
+ ```
1547
+
1548
+ **Graceful Degradation:**
1549
+
1550
+ - Servers SHOULD provide text-only fallback behavior for all UI-enabled tools
1551
+ - Tools MUST return meaningful content array even when UI is available
1552
+ - Servers MAY register different tool variants based on host capabilities
1553
+
1554
+ ### Extensibility
1555
+
1556
+ This specification defines the Minimum Viable Product (MVP) for MCP Apps. Future extensions may include:
1557
+
1558
+ **Content Types (deferred from MVP):**
1559
+
1560
+ - `externalUrl`: Embed external web applications (e.g., `text/uri-list`)
1561
+
1562
+ **Advanced Features (see Future Considerations):**
1563
+
1564
+ - Support multiple UI resources in a tool response
1565
+ - State persistence and restoration
1566
+ - Custom sandbox policies per resource
1567
+ - View-to-View communication
1568
+ - Screenshot/preview generation APIs
1569
+
1570
+ ## Rationale
1571
+
1572
+ This proposal synthesizes feedback from the UI CWG and MCP-UI community, host implementors, and lessons from similar solutions. The guiding principle of this proposal is to start lean and expand in the future. There are breaking changes from existing solutions, which will be addressed via the MCP-UI SDK during the migration period.
1573
+
1574
+ ### Design Decisions
1575
+
1576
+ #### 1. Predeclared Resources vs. Inline Embedding
1577
+
1578
+ **Decision:** Require UI resources to be registered and referenced in tool metadata.
1579
+
1580
+ **Rationale:**
1581
+
1582
+ - Enables hosts to prefetch templates before tool execution, improving performance
1583
+ - Separates presentation (template) from data (tool results), improving caching
1584
+ - Allows hosts to review UI templates
1585
+ - Aligns with MCP's resource discovery pattern
1586
+
1587
+ **Alternatives considered:**
1588
+
1589
+ - **Embedded resources:** Current MCP-UI approach, where resources are returned in tool results. Although it's more convenient for server development, it was deferred due to the gaps in performance optimization and the challenges in the UI review process.
1590
+ - **Resource links:** Predeclare the resources but return links in tool results. Deferred due to the gaps in performance optimization.
1591
+
1592
+ #### 2. Host communication via MCP Transport
1593
+
1594
+ **Decision:** Use MCP's JSON-RPC base protocol over postMessage instead of custom message format.
1595
+
1596
+ **Rationale:**
1597
+
1598
+ - Reuses existing MCP infrastructure (type definitions, error handling, timeouts)
1599
+ - UI developers can use standard MCP SDK (`@modelcontextprotocol/sdk`) or alternatives
1600
+ - Automatic compatibility with future MCP features (long-running tools, sampling, etc.)
1601
+ - Better auditability through structured JSON-RPC messages
1602
+ - Reduces maintenance burden (no parallel protocol to evolve)
1603
+
1604
+ **Alternatives considered:**
1605
+
1606
+ - **Custom message protocol:** Current MCP-UI approach with message types like tool, prompt, etc. These message types can be translated to a subset of the proposed JSON-RPC messages.
1607
+ - **Global API object:** Rejected because it requires host-specific injection and doesn't work with external iframe sources. Syntactic sugar may still be added on the server/UI side.
1608
+
1609
+ #### 3. Support Raw HTML Content Type
1610
+
1611
+ **Decision:** MVP supports only `text/html;profile=mcp-app` (rawHtml), with other types explicitly deferred.
1612
+
1613
+ **Rationale:**
1614
+
1615
+ - HTML is universally supported and well-understood
1616
+ - Simplest security model (standard iframe sandbox)
1617
+ - Allows screenshot/preview generation (e.g., via html2canvas)
1618
+ - Sufficient for most observed use cases
1619
+ - Provides clear baseline for future extensions
1620
+
1621
+ **Alternatives considered:**
1622
+
1623
+ - **Include external URLs in MVP:** This is one of the easiest content types for servers to adopt, as it's possible to embed regular apps. However, it was deferred due to concerns around model visibility, inability to screenshot content, and review process.
1624
+ - **Support multiple content types:** Deferred to maintain a lean MVP.
1625
+
1626
+ #### 4. Host Theming via CSS Variables
1627
+
1628
+ **Decision:** Provide a standardized set of CSS custom properties for visual cohesion.
1629
+
1630
+ **Rationale:**
1631
+
1632
+ - CSS variables are universal, framework-agnostic, and require no runtime
1633
+ - Views apply styles via `var(--name)` with fallbacks for graceful degradation
1634
+ - Limited variable set (colors, typography, borders) ensures hosts can realistically provide all values
1635
+ - Spacing intentionally excluded—layouts break when spacing varies from original design
1636
+ - No UI component library—no single library works across all host environments
1637
+
1638
+ **Alternatives considered:**
1639
+
1640
+ - **Full design system:** Rejected as too prescriptive; hosts have different aesthetics
1641
+ - **Inline styles in tool results:** Rejected; separating theming from data enables caching and updates
1642
+ - **CSS-in-JS injection:** Rejected; framework-specific and security concerns with injected code
1643
+
1644
+ #### 5. Tool Visibility via Metadata
1645
+
1646
+ **Decision:** Use `_meta.ui.visibility` array to control tool accessibility between model and app.
1647
+
1648
+ **Rationale:**
1649
+
1650
+ - Nested `_meta.ui` structure groups all UI-related metadata cleanly
1651
+ - Array format (`["model", "app"]`) allows flexible combinations
1652
+ - Default `["model", "app"]` allows both agent and app to access tools
1653
+ - `"app"` scope is per-server, preventing cross-server tool calls
1654
+ - Cleaner than OpenAI's two-field approach (`widgetAccessible` + `visibility`)
1655
+
1656
+ **Alternatives considered:**
1657
+
1658
+ - **Two separate fields:** OpenAI uses `widgetAccessible` and `visibility` separately. Rejected as redundant; single `visibility` array covers all cases.
1659
+ - **Boolean `private` flag:** Simpler but less flexible; doesn't express model-only tools.
1660
+ - **Flat `ui/visibility` key:** Rejected in favor of nested structure for consistency with future `_meta.ui` fields.
1661
+
1662
+ ### Backward Compatibility
1663
+
1664
+ The proposal builds on the existing core protocol. There are no incompatibilities.
1665
+
1666
+ ### Reference Implementation
1667
+
1668
+ The MCP-UI project serves as a reference implementation demonstrating the core concept, though it uses pre-SEP patterns.
1669
+
1670
+ Olivier Chafik has developed a prototype demonstrating the pattern described in this SEP.
1671
+
1672
+ ## Security Implications
1673
+
1674
+ Hosting interactive UI content from potentially untrusted MCP servers requires careful security consideration.
1675
+
1676
+ ### Threat Model
1677
+
1678
+ Attackers may use the embedded UI in different scenarios. For example:
1679
+
1680
+ - Malicious server delivers harmful HTML content
1681
+ - Compromised View attempts to escape sandbox
1682
+ - View attempts unauthorized tool execution
1683
+ - View exfiltrates sensitive host data
1684
+ - View performs phishing or social engineering
1685
+
1686
+ ### Mitigations
1687
+
1688
+ #### 1. Iframe Sandboxing
1689
+
1690
+ All View content MUST be rendered in sandboxed iframes with restricted permissions.
1691
+
1692
+ The sandbox limits the View from accessing the host or manipulating it. All communication with the host is done via `postMessage`, where the host is in control.
1693
+
1694
+ #### 2. Auditable Communication
1695
+
1696
+ All View-to-host communication goes through auditable MCP JSON-RPC messages.
1697
+
1698
+ **Host behavior:**
1699
+
1700
+ - Validate all incoming messages from UI iframes
1701
+ - Reject malformed message types
1702
+ - Log View-initiated RPC calls for security review
1703
+
1704
+ #### 3. Predeclared Resource Review
1705
+
1706
+ Hosts receive UI templates during connection setup, before tool execution.
1707
+
1708
+ **Host behavior:**
1709
+
1710
+ - Review HTML content for obvious malicious patterns
1711
+ - Generate hash/signature for resources
1712
+ - Warn users about suspicious content
1713
+ - Implement allowlists/blocklists based on resource hashes
1714
+
1715
+ #### 4. Content Security Policy Enforcement
1716
+
1717
+ Hosts MUST enforce Content Security Policies based on resource metadata.
1718
+
1719
+ **CSP Construction from Metadata:**
1720
+
1721
+ ```typescript
1722
+ const csp = resource._meta?.ui?.csp; // `resource` is extracted from the `contents` of the `resources/read` result
1723
+ const permissions = resource._meta?.ui?.permissions;
1724
+
1725
+ const cspValue = `
1726
+ default-src 'none';
1727
+ script-src 'self' 'unsafe-inline' ${csp?.resourceDomains?.join(' ') || ''};
1728
+ style-src 'self' 'unsafe-inline' ${csp?.resourceDomains?.join(' ') || ''};
1729
+ connect-src 'self' ${csp?.connectDomains?.join(' ') || ''};
1730
+ img-src 'self' data: ${csp?.resourceDomains?.join(' ') || ''};
1731
+ font-src 'self' ${csp?.resourceDomains?.join(' ') || ''};
1732
+ media-src 'self' data: ${csp?.resourceDomains?.join(' ') || ''};
1733
+ frame-src ${csp?.frameDomains?.join(' ') || "'none'"};
1734
+ object-src 'none';
1735
+ base-uri ${csp?.baseUriDomains?.join(' ') || "'self'"};
1736
+ `;
1737
+
1738
+ // Permission Policy for iframe allow attribute
1739
+ const allowList: string[] = [];
1740
+ if (permissions?.camera) allowList.push('camera');
1741
+ if (permissions?.microphone) allowList.push('microphone');
1742
+ if (permissions?.geolocation) allowList.push('geolocation');
1743
+ const allowAttribute = allowList.join(' ');
1744
+ ```
1745
+
1746
+ **Security Requirements:**
1747
+
1748
+ - Host MUST block connections to undeclared domains
1749
+ - Host SHOULD warn users when UI requires external domain access
1750
+ - Host MAY implement global domain allowlists/blocklists
1751
+
1752
+ ### Other risks
1753
+
1754
+ - **Social engineering:** UI can still display misleading content. Hosts should clearly indicate sandboxed UI boundaries.
1755
+ - **Resource consumption:** Malicious View can consume CPU/memory. Hosts should implement resource limits.
1756
+
1757
+ ## Reservations in MCP
1758
+
1759
+ - The resource prefix `ui://` will be reserved for MCP Apps
1760
+ - The label `io.modelcontextprotocol/ui` is reserved