MCP Apps
This page is for developers who build or support a host that draws MCP Apps, and for anyone who wants to know what instruction.md shows inside Claude or ChatGPT. It lists the apps the MCP server offers, the tools that open each one, what each button calls, and how the links are declared.
What the apps are
An MCP App is a view a host draws in the conversation, beside a tool's answer. instruction.md's are 3 single HTML files, served as ui:// resources of the type text/html;profile=mcp-app. A tool's descriptor names the app that goes with it. When a host that supports MCP Apps calls that tool, it reads the app and draws it with the tool's answer.
Inside the app, every button is a tool call that the host makes for it, as the signed-in person. The app has no token of its own and reaches nothing on the network itself. What it may do is what the person may do: a Reader sees the buttons for reading, and the server refuses anything else.
The app never sends an instruction's text to the host's model. After a change it tells the model, in one English sentence, what the person did and that it should read again. For example: "In instruction.md, the person published acme/support-agent as v3."
The apps
| App | Address | Opened by |
|---|---|---|
| Browse instructions | ui://instruction.md/browse | instructions_list, instructions_proposals_list, instructions_versions_list |
| Review a proposal | ui://instruction.md/review | instructions_proposals_get |
| An instruction's draft | ui://instruction.md/draft | instructions_get, instructions_create |
The draft
Opened by instructions_get and instructions_create. The instruction the tool read or made: its draft drawn as the site draws it (or as Markdown), the suggested changes waiting on it, what the checks find, and its open comments. A reader of a published instruction sees the live version. While it is on screen it looks again every few seconds, so a change the model makes shows without a reload.
| Button | What it calls |
|---|---|
| Accept | instructions_suggestions_accept: also Accept all |
| Reject | instructions_suggestions_reject: also Reject all |
| Edit / Suggest an edit, then Save / Send as suggestions | instructions_draft_replace: a Contributor's text lands as suggestions |
| Publish | instructions_publish: asks what changed (and, the first time, who can read it), then shows the server's confirmation |
| Comment | instructions_comments_create |
| Reply | instructions_comments_reply |
| Resolve | instructions_comments_resolve |
| Ask | sends your words to the conversation, for the host's model to act on |
| Open in the editor | opens the instruction in the editor |
| Full screen | where the host offers full screen |
The host's model does the writing. A request typed in Ask, or one of the ready ones such as Check it for problems and fix them, is sent to the conversation as the person's message. When the person may only suggest, the message asks the model to make its changes as suggestions. The person then accepts or rejects them in the app.
Publish is turned off while the checks find a problem that would stop a release. It asks for what changed (and, for the first version, who can read it), then shows the server's own confirmation before anything is released.
Browse
Opened by instructions_list, instructions_proposals_list, instructions_versions_list. A list of the instructions you can see, with a filter, from instructions_list. From instructions_versions_list or instructions_proposals_list it opens on that instruction's history or proposals. Opening a proposal shows the same review as the review app.
| Tab | What it calls |
|---|---|
| Versions | instructions_versions_list |
| Proposals | instructions_proposals_list |
Review
Opened by instructions_proposals_get. One proposal, as a diff against the version it was based on (instructions_proposals_get with its texts), its reviews, and the actions your role allows. Its author can't approve it.
| Button | What it calls |
|---|---|
| Approve | instructions_proposals_review: verdict approve, with an optional comment; needs the publish permission |
| Request changes | instructions_proposals_review: verdict request_changes; needs the suggest permission |
| Merge and publish | instructions_proposals_merge: shows the server's confirmation first |
| Rebase | instructions_proposals_update: rebase: true, when the proposal is stale |
| Close | instructions_proposals_close |
| Reject | instructions_proposals_close: reject: true |
Merge and publish releases a new version, so the server asks first and the app shows its summary and consequences, with Confirm and Cancel. Merging takes the publish permission. How proposals work is on Tool reference.
How links are declared
A tool names its app in its descriptor's _meta.ui.resourceUri, which tools/list returns. visibility: ["model", "app"] says that both the model and the app may call the tool.
{
"name": "instructions_proposals_get",
"_meta": {
"md.instruction/class": "read",
"md.instruction/toolset": "review",
"ui": {
"resourceUri": "ui://instruction.md/review",
"visibility": [
"model",
"app"
]
},
"anthropic/maxResultSizeChars": 150000
}
} The host reads the app with resources/read. Its answer is the whole app in one HTML file. _meta.ui.prefersBorder asks the host to draw a border around it.
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"contents": [
{
"uri": "ui://instruction.md/review",
"mimeType": "text/html;profile=mcp-app",
"text": "<!doctype html><html>…</html>",
"_meta": {
"ui": {
"prefersBorder": true
}
}
}
]
}
} Some tools have visibility: ["app"]: they are for an app's frame only, and never shown to a model. They are the editor's own, and the gateway lets only its first-party clients (platform-web and instruction-cli) call them. An app drawn in a host can't call them.
instructions_metapages_getinstructions_draft_syncinstructions_checkpoints_createorgs_invitations_peekme_notifications_readme_apps_consent_getme_apps_grantsupport_requests_listsupport_requests_getsupport_requests_updatesupport_requests_recoverinstructions_presence_set
The frame
The gateway serves the apps with no extra permissions: no camera, microphone or other device. Each app loads under a policy that lets it fetch nothing, so everything it needs, its translations included, is in its one file.
An app speaks the host's language when it has it: English, Arabic, Spanish, French, Ukrainian. It takes the host's light or dark theme. Full screen shows only where the host offers a full-screen mode.
Host support
The apps follow the MCP Apps extension, and are drawn by hosts that support it, such as Claude and ChatGPT. A host that doesn't support MCP Apps ignores the link and shows the tool's answer as usual. Nothing depends on the app: every tool answers the same with or without it, and the model works from the answer.
If an app can't reach its host in time, it says "The app could not reach its host in time." If a host can't send messages from an app, the draft app says "This app can't send a message here: type it in the conversation instead."