You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+63-28Lines changed: 63 additions & 28 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -47,13 +47,15 @@
47
47
48
48
## Build with Agent Skills
49
49
50
-
The fastest way to build an MCP App is to let your AI coding agent do it. This repo ships four [Agent Skills](https://agentskills.io/) — install them once, then just ask:
|[`create-mcp-app`](./plugins/mcp-apps/skills/create-mcp-app/SKILL.md)| Scaffolds a new MCP App with an interactive UI from scratch |_"Create an MCP App"_|
55
-
|[`migrate-oai-app`](./plugins/mcp-apps/skills/migrate-oai-app/SKILL.md)| Converts an existing OpenAI App to use MCP Apps |_"Migrate from OpenAI Apps SDK"_|
56
-
|[`add-app-to-server`](./plugins/mcp-apps/skills/add-app-to-server/SKILL.md)| Adds interactive UI to an existing MCP server's tools |_"Add UI to my MCP server"_|
50
+
The fastest way to build an MCP App is to let your AI coding agent do it. This
51
+
repo ships four [Agent Skills](https://agentskills.io/) — install them once,
|[`create-mcp-app`](./plugins/mcp-apps/skills/create-mcp-app/SKILL.md)| Scaffolds a new MCP App with an interactive UI from scratch |_"Create an MCP App"_|
57
+
|[`migrate-oai-app`](./plugins/mcp-apps/skills/migrate-oai-app/SKILL.md)| Converts an existing OpenAI App to use MCP Apps |_"Migrate from OpenAI Apps SDK"_|
58
+
|[`add-app-to-server`](./plugins/mcp-apps/skills/add-app-to-server/SKILL.md)| Adds interactive UI to an existing MCP server's tools |_"Add UI to my MCP server"_|
57
59
|[`convert-web-app`](./plugins/mcp-apps/skills/convert-web-app/SKILL.md)| Turns an existing web app into a hybrid web + MCP App |_"Add MCP App support to my web app"_|
58
60
59
61
### Install the Skills
@@ -65,9 +67,15 @@ The fastest way to build an MCP App is to let your AI coding agent do it. This r
**Other agents** — any AI coding agent that supports [Agent Skills](https://agentskills.io/) can use these skills. See the [agent skills guide](./docs/agent-skills.md) for manual installation instructions.
70
+
**Other agents** — any AI coding agent that supports
71
+
[Agent Skills](https://agentskills.io/) can use these skills. See the
72
+
[agent skills guide](./docs/agent-skills.md) for manual installation
73
+
instructions.
69
74
70
-
Once installed, verify by asking your agent _"What skills do you have?"_ — you should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and `convert-web-app` in the list. Then just ask it to create or migrate an app and it will guide you through the rest.
75
+
Once installed, verify by asking your agent _"What skills do you have?"_ — you
76
+
should see `create-mcp-app`, `migrate-oai-app`, `add-app-to-server`, and
77
+
`convert-web-app` in the list. Then just ask it to create or migrate an app and
78
+
it will guide you through the rest.
71
79
72
80
## Supported Clients
73
81
@@ -80,35 +88,47 @@ Once installed, verify by asking your agent _"What skills do you have?"_ — you
> MCP Apps is an extension to the [core MCP specification](https://modelcontextprotocol.io/specification). Host support varies — see the [clients page](https://modelcontextprotocol.io/clients) for the full list.
> [clients page](https://modelcontextprotocol.io/clients) for the full list.
85
95
86
96
## Why MCP Apps?
87
97
88
-
MCP tools return text and structured data. That works for many cases, but not when you need an interactive UI, like a chart, form, or video player.
98
+
MCP tools return text and structured data. That works for many cases, but not
99
+
when you need an interactive UI, like a chart, form, or video player.
89
100
90
-
MCP Apps provide a standardized way to deliver interactive UIs from MCP servers. Your UI renders inline in the conversation, in context, in any compliant host.
101
+
MCP Apps provide a standardized way to deliver interactive UIs from MCP servers.
102
+
Your UI renders inline in the conversation, in context, in any compliant host.
91
103
92
104
## How It Works
93
105
94
-
MCP Apps extend the Model Context Protocol by letting tools declare UI resources:
106
+
MCP Apps extend the Model Context Protocol by letting tools declare UI
107
+
resources:
95
108
96
-
1.**Tool definition** — Your tool declares a `ui://` resource containing its HTML interface
109
+
1.**Tool definition** — Your tool declares a `ui://` resource containing its
110
+
HTML interface
97
111
2.**Tool call** — The LLM calls the tool on your server
98
-
3.**Host renders** — The host fetches the resource and displays it in a sandboxed iframe
99
-
4.**Bidirectional communication** — The host passes tool data to the UI via notifications, and the UI can call other tools through the host
112
+
3.**Host renders** — The host fetches the resource and displays it in a
113
+
sandboxed iframe
114
+
4.**Bidirectional communication** — The host passes tool data to the UI via
115
+
notifications, and the UI can call other tools through the host
100
116
101
117
## Getting Started
102
118
103
119
```bash
104
120
npm install -S @modelcontextprotocol/ext-apps
105
121
```
106
122
107
-
**New here?** Start with the [Quickstart Guide](https://modelcontextprotocol.github.io/ext-apps/api/documents/Quickstart.html) to build your first MCP App.
The SDK serves three roles: app developers building interactive Views, host developers embedding those Views, and MCP server authors registering tools with UI metadata.
129
+
The SDK serves three roles: app developers building interactive Views, host
130
+
developers embedding those Views, and MCP server authors registering tools with
@@ -117,13 +137,19 @@ The SDK serves three roles: app developers building interactive Views, host deve
117
137
|`@modelcontextprotocol/ext-apps/app-bridge`| Embed and communicate with Views in your chat client |[API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/app-bridge.html)|
118
138
|`@modelcontextprotocol/ext-apps/server`| Register tools and resources on your MCP server |[API Docs →](https://modelcontextprotocol.github.io/ext-apps/api/modules/server.html)|
119
139
120
-
There's no _supported_ host implementation in this repo (beyond the [examples/basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example).
140
+
There's no _supported_ host implementation in this repo (beyond the
The [MCP-UI](https://github.com/idosal/mcp-ui) client SDK offers a fully-featured MCP Apps framework used by a few hosts. Clients may choose to use it or roll their own implementation.
144
+
The [MCP-UI](https://github.com/idosal/mcp-ui) client SDK offers a
145
+
fully-featured MCP Apps framework used by a few hosts. Clients may choose to use
146
+
it or roll their own implementation.
123
147
124
148
## Examples
125
149
126
-
The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains demo apps showcasing real-world use cases.
directory contains demo apps showcasing real-world use cases.
127
153
128
154
<!-- prettier-ignore-start -->
129
155
||||
@@ -150,7 +176,9 @@ The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/exa
150
176
151
177
#### With basic-host
152
178
153
-
To run all examples locally using [basic-host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) (the reference host implementation included in this repo):
@@ -163,7 +191,9 @@ Then open http://localhost:8080/.
163
191
164
192
#### With MCP Clients
165
193
166
-
Every Node.js example is published as `@modelcontextprotocol/server-<name>`. To add one to an MCP client that supports stdio (Claude Desktop, VS Code, etc.), use this pattern:
194
+
Every Node.js example is published as `@modelcontextprotocol/server-<name>`. To
195
+
add one to an MCP client that supports stdio (Claude Desktop, VS Code, etc.),
196
+
use this pattern:
167
197
168
198
```json
169
199
{
@@ -176,11 +206,14 @@ Every Node.js example is published as `@modelcontextprotocol/server-<name>`. To
176
206
}
177
207
```
178
208
179
-
For example, to add the map server: `@modelcontextprotocol/server-map`. The Python examples (`qr-server`, `say-server`) use `uv run` instead — see their READMEs for details.
209
+
For example, to add the map server: `@modelcontextprotocol/server-map`. The
210
+
Python examples (`qr-server`, `say-server`) use `uv run` instead — see their
211
+
READMEs for details.
180
212
181
213
#### Local Development
182
214
183
-
To test local modifications with an MCP client, clone the repo, install, then point your client at a local build:
215
+
To test local modifications with an MCP client, clone the repo, install, then
216
+
point your client at a local build:
184
217
185
218
```json
186
219
{
@@ -211,9 +244,11 @@ To test local modifications with an MCP client, clone the repo, install, then po
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to get started, submit pull requests, and report issues.
253
+
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
254
+
guidelines on how to get started, submit pull requests, and report issues.
0 commit comments