Cette page n’est pas encore traduite.

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 review app, opened beside instructions_proposals_get.

The apps

AppAddressOpened by
Browse instructionsui://instruction.md/browseinstructions_list, instructions_proposals_list, instructions_versions_list
Review a proposalui://instruction.md/reviewinstructions_proposals_get
An instruction's draftui://instruction.md/draftinstructions_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.

ButtonWhat it calls
Acceptinstructions_suggestions_accept: also Accept all
Rejectinstructions_suggestions_reject: also Reject all
Edit / Suggest an edit, then Save / Send as suggestionsinstructions_draft_replace: a Contributor's text lands as suggestions
Publishinstructions_publish: asks what changed (and, the first time, who can read it), then shows the server's confirmation
Commentinstructions_comments_create
Replyinstructions_comments_reply
Resolveinstructions_comments_resolve
Asksends your words to the conversation, for the host's model to act on
Open in the editoropens the instruction in the editor
Full screenwhere the host offers full screen
The draft app, opened beside instructions_get and instructions_create.

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.

TabWhat it calls
Versionsinstructions_versions_list
Proposalsinstructions_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.

ButtonWhat it calls
Approveinstructions_proposals_review: verdict approve, with an optional comment; needs the publish permission
Request changesinstructions_proposals_review: verdict request_changes; needs the suggest permission
Merge and publishinstructions_proposals_merge: shows the server's confirmation first
Rebaseinstructions_proposals_update: rebase: true, when the proposal is stale
Closeinstructions_proposals_close
Rejectinstructions_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.

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.

instructions_proposals_get in tools/list (excerpt)
{
  "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.

resources/read of an app (text shortened)
{
  "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_meta
  • pages_get
  • instructions_draft_sync
  • instructions_checkpoints_create
  • orgs_invitations_peek
  • me_notifications_read
  • me_apps_consent_get
  • me_apps_grant
  • support_requests_list
  • support_requests_get
  • support_requests_update
  • support_requests_recover
  • instructions_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."

Last checked against the product:

Was this page helpful? Report a problem