Skip to content

Commit 5411141

Browse files
localdenlocalden
authored
Merge pull request modelcontextprotocol#1865 from idosal/main
SEP-1865: MCP Apps - Interactive User Interfaces for MCP
2 parents 222ba8e + b7ab514 commit 5411141

7 files changed

Lines changed: 348 additions & 31 deletions

‎docs/community/seps/1865-mcp-apps-interactive-user-interfaces-for-mcp.mdx‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: "SEP-1865: MCP Apps - Interactive User Interfaces for MCP"
3+
sidebarTitle: "SEP-1865: MCP Apps - Interactive User Interfaces…"
4+
description: "MCP Apps - Interactive User Interfaces for MCP"
5+
---
6+
7+
import { Badge } from "/snippets/badge.mdx";
8+
9+
<div className="flex items-center gap-2 mb-4">
10+
<Badge color="green">Final</Badge>
11+
<Badge color="gray">Extensions Track</Badge>
12+
</div>
13+
14+
| Field | Value |
15+
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16+
| **SEP** | 1865 |
17+
| **Title** | MCP Apps - Interactive User Interfaces for MCP |
18+
| **Status** | Final |
19+
| **Type** | Extensions Track |
20+
| **Created** | 2025-11-21 |
21+
| **Author(s)** | Ido Salomon ([@idosal](https://github.com/idosal)), Liad Yosef ([@liadyosef](https://github.com/liadyosef)), Olivier Chafik ([@olivierchafik](https://github.com/olivierchafik)), |
22+
| **Sponsor** | None (seeking sponsor) |
23+
| **PR** | [#1865](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1865) |
24+
25+
---
26+
27+
## Abstract
28+
29+
This SEP proposes an extension to MCP (per SEP-1724) that enables servers to deliver interactive
30+
user interfaces to hosts. MCP Apps introduces a standardized pattern for declaring UI resources via
31+
the `ui://` URI scheme, associating them with tools through metadata, and facilitating
32+
bi-directional communication between the UI and the host using MCP's JSON-RPC base protocol. This
33+
extension addresses the growing community need for rich, interactive experiences in MCP-enabled
34+
applications, maintaining security, auditability, and alignment with MCP's core architecture. The
35+
initial specification focuses on HTML resources (`text/html;profile=mcp-app`) with a clear path for
36+
future extensions.
37+
38+
## Motivation
39+
40+
MCP lacks a standardized way for servers to deliver rich, interactive user interfaces to hosts.
41+
This gap blocks many use cases that require visual presentation and interactivity that go beyond
42+
plain text or structured data. As more hosts adopt this capability, the risk of fragmentation and
43+
interoperability challenges grows.
44+
45+
[MCP-UI](https://mcpui.dev/) has demonstrated the viability and value of MCP apps built on UI
46+
resources and serves as a community playground for the UI spec and SDK. Fueled by a dedicated
47+
community, it developed the bi-directional communication model and the HTML, external URL, and
48+
remote DOM content types. MCP-UI's adopters, including hosts and providers such as Postman,
49+
HuggingFace, Shopify, Goose, and ElevenLabs, have provided critical insights and contributions to
50+
the community.
51+
52+
OpenAI's [Apps SDK](https://developers.openai.com/apps-sdk/), launched in November 2025, further
53+
validated the demand for rich UI experiences within conversational AI interfaces. The Apps SDK
54+
enables developers to build rich, interactive applications inside ChatGPT using MCP as its
55+
backbone.
56+
57+
The architecture of both the Apps SDK and MCP-UI has significantly informed the design of this
58+
specification.
59+
60+
However, without formal standardization:
61+
62+
- Servers cannot reliably expect UI support via MCP
63+
- Each host may implement slightly different behaviors
64+
- Security and auditability patterns are inconsistent
65+
- Developers must maintain separate implementations or adapters for different hosts (e.g., MCP-UI
66+
vs. Apps SDK)
67+
68+
This SEP addresses the current limitations through an optional, backwards-compatible extension that
69+
unifies the approaches pioneered by MCP-UI and the Apps SDK into a single, open standard.
70+
71+
## Specification
72+
73+
The full specification can be found at
74+
[modelcontextprotocol/ext-apps](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx).
75+
76+
At a high level, MCP Apps extends the Model Context Protocol to enable servers to deliver
77+
interactive user interfaces to hosts. This extension introduces:
78+
79+
- **UI Resources:** Predeclared resources using the `ui://` URI scheme
80+
- **Resource Discovery:** Tools reference UI resources via metadata
81+
- **Bi-directional Communication:** UI iframes communicate with hosts using standard MCP JSON-RPC
82+
protocol
83+
- **Security Model:** Mandatory iframe sandboxing with auditable communication
84+
85+
This specification focuses on HTML content (`text/html;profile=mcp-app`) as the initial content
86+
type, with extensibility for future formats.
87+
88+
As an extension, MCP Apps is optional and must be explicitly negotiated between clients and servers
89+
through the extension capabilities mechanism (see Capability Negotiation section in the
90+
[full specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx)).
91+
92+
## Rationale
93+
94+
### Predeclared resources vs. inline embedding
95+
96+
UI is modeled as predeclared resources (`ui://`), referenced by tools via metadata. This allows:
97+
98+
- Hosts to prefetch templates before tool execution, improving performance
99+
- Separation of presentation (template) from data (tool results), facilitating caching
100+
- Security review of UI resources
101+
102+
**Alternatives considered:**
103+
104+
- **Embedded resources:** Current MCP-UI approach, where resources are returned in tool results.
105+
Although it's more convenient for server development, it was deferred due to the gaps in
106+
performance optimization and the challenges in the UI review process.
107+
- **Resource links:** Predeclare the resources but return links in tool results. Deferred due to
108+
the gaps in performance optimization.
109+
110+
### Reusing MCP JSON-RPC instead of a custom protocol
111+
112+
Reuses existing MCP infrastructure (type definitions, SDKs, etc.). JSON-RPC offers advanced
113+
capabilities (timeouts, errors, etc.).
114+
115+
**Alternatives considered:**
116+
117+
- **Custom message protocol:** Current MCP-UI approach with message types like tool, intent,
118+
prompt, etc. These message types can be translated to a subset of the proposed JSON-RPC messages.
119+
- **Global API object:** Rejected because it requires host-specific injection and doesn't work with
120+
external iframe sources. Syntactic sugar may still be added on the server/UI side.
121+
122+
### HTML-only MVP
123+
124+
- HTML is universally supported and well-understood
125+
- Simplest security model (standard iframe sandbox)
126+
- Allows screenshot/preview generation (e.g., via html2canvas)
127+
- Sufficient for most observed use cases
128+
- Provides a clear baseline for future extensions
129+
130+
**Alternatives considered:**
131+
132+
- **Include external URLs in MVP:** This is one of the easiest content types for servers to adopt,
133+
as it's possible to embed regular apps. However, it was deferred due to concerns around model
134+
visibility, inability to screenshot content, and review process. It may effectively be supported
135+
with the SEP's new `externalIframes` capability.
136+
137+
## Backward Compatibility
138+
139+
The proposal is an optional extension to the core protocol. Existing implementations continue
140+
working without changes.
141+
142+
## Security Implications
143+
144+
Hosting interactive UI content from potentially untrusted MCP servers requires careful security
145+
consideration.
146+
147+
Based on the threat model, MCP Apps proposes the following mitigations:
148+
149+
- **Iframe sandboxing**: All UI content runs in sandboxed iframes with restricted permissions
150+
- **Predeclared templates**: Hosts can review HTML content before rendering
151+
- **Auditable messages**: All UI-to-host communication goes through loggable JSON-RPC
152+
- **User consent**: Hosts can require explicit approval for UI-initiated tool calls
153+
154+
A full threat model analysis and mitigations are available in the
155+
[full specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx).
156+
157+
## Reference Implementation
158+
159+
- [MCP-UI](https://github.com/idosal/mcp-ui) client and server SDKs support the patterns proposed
160+
in this spec.
161+
- [ext-apps](https://github.com/modelcontextprotocol/ext-apps) repository contains a prototype
162+
implementation by Olivier Chafik.

0 commit comments

Comments
 (0)