Skip to content

Commit 9c80066

Browse files
Standardize notification naming and fix formatting in MCP Apps spec
Updates the MCP Apps specification to consistently use the `ui/notifications/` prefix for all notification methods (e.g., `ui/notifications/sandbox-ready`, `ui/notifications/tool-result`). Also removes trailing whitespace, fixes tab/space inconsistencies, improves code formatting with proper backticks, and clarifies terminology throughout the document. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent f96c526 commit 9c80066

File tree

1 file changed

+22
-22
lines changed

1 file changed

+22
-22
lines changed

specification/draft/apps.mdx

Lines changed: 22 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# SEP-1865: MCP Apps: Interactive User Interfaces for MCP
22

3-
**Track:** Extensions
4-
**Authors:** Ido Salomon, Liad Yosef, Olivier Chafik, Jerome Swannack, Jonathan Hefner, Anton Pidkuiko, Nick Cooper, Bryan Ashley, Alexei Christakis
5-
**Status:** Draft
3+
**Track:** Extensions
4+
**Authors:** Ido Salomon, Liad Yosef, Olivier Chafik, Jerome Swannack, Jonathan Hefner, Anton Pidkuiko, Nick Cooper, Bryan Ashley, Alexei Christakis
5+
**Status:** Draft
66
**Created:** 2025-11-21
77

88
## Abstract
@@ -86,7 +86,7 @@ The resource content is returned via `resources/read`:
8686
connect_domains?: string[]; // Origins for fetch/XHR/WebSocket
8787
resource_domains?: string[]; // Origins for images, scripts, etc
8888
};
89-
"domain"?: string;
89+
"domain"?: string;
9090
"prefersBorder"?: boolean;
9191
};
9292
};
@@ -293,14 +293,14 @@ If the Host is a web page, it MUST wrap the Guest UI and communicate with it thr
293293

294294
1. The Host and the Sandbox MUST have different origins.
295295
2. The Sandbox MUST have the following permissions: `allow-scripts`, `allow-same-origin`.
296-
3. The Sandbox MUST send a `ui/sandbox-ready` notification to the host when it’s ready to process an `ui/sandbox-resource-ready` notification.
297-
4. Once the Sandbox is ready, the Host MUST send the raw HTML resource to load in a `ui/sandbox-resource-ready` notification.
296+
3. The Sandbox MUST send a `ui/notifications/sandbox-ready` notification to the host when it’s ready to process an `ui/sandbox-resource-ready` notification.
297+
4. Once the Sandbox is ready, the Host MUST send the raw HTML resource to load in a `ui/notifications/sandbox-resource-ready` notification.
298298
5. The Sandbox MUST load the raw HTML of the Guest UI with CSP settings that:
299299
- Enforce the domains declared in `ui.csp` metadata
300300
- Prevent nested iframes (`frame-src 'none'`)
301301
- Block dangerous features (`object-src 'none'`, `base-uri 'self'`)
302302
- Apply restrictive defaults if no CSP metadata is provided
303-
6. The Sandbox MUST forward messages sent by the Host to the Guest UI, and vice versa, with any method that doesn’t start with `ui/sandbox-`. This includes lifecycle messages, e.g. `initialize` request & `initialized` notification both sent by the Guest UI. The Host MUST NOT send any request or notification to the Guest UI before it receives an `initialized` notification.
303+
6. The Sandbox MUST forward messages sent by the Host to the Guest UI, 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 Guest UI. The Host MUST NOT send any request or notification to the Guest UI before it receives an `initialized` notification.
304304
7. The Sandbox SHOULD NOT create/send any requests to the Host or to the Guest UI (this would require synthesizing new request ids).
305305
8. The Host MAY forward any message from the Guest UI (coming via the Sandbox) to the MCP Apps server, for any method that doesn’t start with `ui/`. While the Host SHOULD ensure the Guest UI’s MCP connection is spec-compliant, it MAY decide to block some messages or subject them to further user approval.
306306

@@ -325,7 +325,7 @@ UI iframes can use the following subset of standard MCP protocol messages:
325325
- `ui/initialize``ui/notifications/initialized` - MCP-like handshake (replaces custom iframe-ready pattern in MCP-UI)
326326
- `ping` - Connection health check
327327

328-
### Host Context in McpUiInitializeResult
328+
### Host Context in `McpUiInitializeResult`
329329

330330
When the Guest UI sends an `ui/initialize` request to the Host, the Host SHOULD include UI-specific context in the `McpUiInitializeResult`’s `hostContext` field:
331331

@@ -486,7 +486,7 @@ Host SHOULD add the message to the conversation thread, preserving the specified
486486
}
487487
```
488488

489-
Host sends this notification after the Guest UI's initialize request completes, when tool arguments become available. This notification is sent at most once and is required before sending `ui/tool-result`.
489+
Host sends this notification after the Guest UI's initialize request completes, when tool arguments become available. This notification is sent at most once and is required before sending `ui/notifications/tool-result`.
490490

491491
`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.
492492

@@ -513,12 +513,12 @@ Guest UI behavior (optional):
513513
- MUST NOT rely on partial arguments for critical operations
514514
- SHOULD gracefully handle missing or changing fields between notifications
515515

516-
`ui/tool-result` - Tool execution result
516+
`ui/notifications/tool-result` - Tool execution result
517517

518518
```json
519519
{
520520
"jsonrpc": "2.0",
521-
"method": "ui/tool-result",
521+
"method": "ui/notifications/tool-result",
522522
"params": "CallToolResult" // Standard MCP type
523523
}
524524
```
@@ -603,22 +603,22 @@ Host MAY send this notification when any context field changes (e.g., theme togg
603603

604604
These messages are reserved for web-based hosts that implement the recommended double-iframe sandbox architecture:
605605

606-
`ui/sandbox-ready` - Sandbox proxy is ready
606+
`ui/notifications/sandbox-ready` (Sandbox Proxy → Host) - Sandbox proxy is ready
607607

608608
```json
609609
{
610610
"jsonrpc": "2.0",
611-
"method": "ui/sandbox-ready",
611+
"method": "ui/notifications/sandbox-ready",
612612
"params": {}
613613
}
614614
```
615615

616-
`ui/sandbox-resource-ready` - HTML resource ready to load
616+
`ui/notifications/sandbox-resource-ready` (Host → Sandbox Proxy) - HTML resource ready to load
617617

618618
```json
619619
{
620620
"jsonrpc": "2.0",
621-
"method": "ui/sandbox-resource-ready",
621+
"method": "ui/notifications/sandbox-resource-ready",
622622
"params": {
623623
"html": "string", // HTML content to load
624624
"sandbox": "string" // Optional override for inner iframe `sandbox` attribute
@@ -666,9 +666,9 @@ sequenceDiagram
666666
P -> P: Render inner iframe with HTML
667667
668668
end
669-
UI ->> H: initialize
670-
H -->> UI: InitializeResult (e.g., host-context, capabilities, etc.)
671-
UI ->> H: notifications/initialized
669+
UI ->> H: ui/initialize
670+
H -->> UI: McpUiInitializeResult (e.g., host-context, capabilities, etc.)
671+
UI ->> H: ui/notifications/initialized
672672
opt Stream Tool input to UI
673673
H -->> UI: ui/notifications/tool-input-partial (0..n)
674674
end
@@ -681,7 +681,7 @@ sequenceDiagram
681681
end
682682
```
683683

684-
Note: when the Guest UI is rendered inside a sandbox, the sandbox transparently passes events between the Guest UI and the Host (except for events that start with `sandbox-`)
684+
Note: when the Guest UI is rendered inside a sandbox, the sandbox transparently passes messages between the Guest UI and the Host, except for messages named `ui/notifications/sandbox-*`.
685685

686686
#### 5. Interactive Phase
687687

@@ -746,7 +746,7 @@ Note: Cleanup may be triggered at any point in the lifecycle following UI initia
746746

747747
Tool execution results are passed to the UI through two mechanisms:
748748

749-
#### 1. Tool Input (via ui/notifications/tool-input notification)
749+
#### 1. Tool Input (via `ui/notifications/tool-input` notification)
750750

751751
The original tool call arguments:
752752

@@ -761,7 +761,7 @@ params: {
761761
}
762762
```
763763

764-
#### 2. Tool Result (via ui/tool-result notification)
764+
#### 2. Tool Result (via `ui/notifications/tool-result` notification)
765765

766766
The tool's execution result:
767767

@@ -783,7 +783,7 @@ The tool's execution result:
783783
}
784784

785785
// UI receives:
786-
Notification: ui/tool-result
786+
Notification: ui/notifications/tool-result
787787
params: {
788788
content: [...], // Same as above
789789
structuredContent: { temperature: 72, ... },

0 commit comments

Comments
 (0)