Core Summary

MCP Apps is the official optional UI extension for the Model Context Protocol. In the stable 2026-01-26 specification, a Tool points to a ui:// Resource through _meta.ui.resourceUri; a supporting Host fetches the HTML, renders it in a sandboxed View, and mediates a JSON-RPC channel between the View and the MCP Server. This standardizes an interactive surface, not identity, authorization, billing, distribution, or business correctness.

The Protocol Boundary

The extension identifier is io.modelcontextprotocol/ui. It introduces four important contracts:

  1. UI Resource: a predeclared ui:// Resource containing text/html;profile=mcp-app.
  2. Tool-to-UI linkage: Tool metadata identifies the Resource used to render the result.
  3. View-to-Host protocol: the iframe and Host exchange JSON-RPC messages over postMessage.
  4. Security metadata: the Resource declares CSP origins, requested browser permissions, and display preferences.
text
User
  |
  v
Host / Agent ----- tools/call -----> MCP Server
  |                                     |
  | resources/read                      | Tool result
  v                                     v
Sandboxed View <---- UI messages ---- Host bridge

MCP Apps is an extension rather than a mandatory core feature. A Server and Host negotiate support. The same Tool should return meaningful content or structuredContent when the Host cannot render the View.

Declare a UI Resource Correctly

A current Tool declaration nests the reference under _meta.ui:

json
{
  "name": "orders.review",
  "description": "Return a read-only review queue for orders visible to the caller.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "status": {"type": "string", "enum": ["pending", "flagged"]}
    },
    "required": ["status"],
    "additionalProperties": false
  },
  "_meta": {
    "ui": {
      "resourceUri": "ui://orders/review-v3",
      "visibility": ["model", "app"]
    }
  }
}

The Resource returned by resources/read uses the matching URI and MIME type:

json
{
  "contents": [{
    "uri": "ui://orders/review-v3",
    "mimeType": "text/html;profile=mcp-app",
    "text": "<!doctype html><html>...</html>",
    "_meta": {
      "ui": {
        "csp": {
          "connectDomains": ["https://api.example.com"],
          "resourceDomains": ["https://static.example.com"]
        },
        "permissions": {},
        "prefersBorder": true
      }
    }
  }]
}

The earlier flat _meta["ui/resourceUri"] form is deprecated in the stable specification. Pin the extension revision and generated SDK types instead of copying an old example.

Understand the Lifecycle

The lifecycle has distinct phases:

Phase Direction Required concern
discovery Server to Host Tool metadata and supported extension
resource fetch Host to Server exact URI, MIME type, size, cache identity
initialization View and Host ui/initialize, capabilities, origin and session
input/result delivery Host to View bounded, redacted, versioned data
interaction View through Host to Server Tool allowlist, authorization, confirmation
teardown Host and View cleanup, cancellation, retained state

The View should not assume that a Tool result, permission request, open-link capability, or Host feature exists. Feature detection and a non-UI fallback are part of compatibility.

Separate Model Context From View Data

MCP Tool results can carry text content for the model and structuredContent for consumers such as a UI. Minimize both:

  • send the model only the facts needed for reasoning;
  • send the View only fields needed to render the current surface;
  • never use a hidden UI field as authorization;
  • avoid placing credentials, internal object IDs, or raw downstream responses in either channel;
  • attach source and version identifiers when displayed data can become stale.

A chart may need 50 aggregated points while the model needs a two-sentence summary. Duplicating the full dataset into both channels increases privacy and context risk without improving the task.

Visibility Is Not Authorization

The extension allows a Tool to declare whether it is visible to the model, the app, or both. An app-only Tool can keep refresh or local interaction plumbing out of the model's Tool list, and cross-server calls are blocked for that path. These are useful exposure controls, not business authorization.

Every Server call still needs:

  • authenticated subject and tenant from trusted transport context;
  • Tool and object authorization;
  • normalized, schema-valid parameters;
  • current object state and policy;
  • confirmation bound to the exact proposed effect;
  • idempotency and outcome recovery;
  • rate, time, result-size, and cost budgets.

The View submits an intent. It does not decide who the user is, what an order costs, or whether a side effect is allowed.

A Runnable Server-Side Action Gate

The following Go program models a confirmation token bound to a subject, action, object, amount, and expiry. It deliberately ignores any identity or price asserted by the UI:

go
package main

import (
	"fmt"
	"time"
)

type Session struct {
	Subject string
	Tenant  string
}

type Confirmation struct {
	ID        string
	Subject   string
	Tenant    string
	Action    string
	ObjectID  string
	Amount    int
	ExpiresAt time.Time
	Consumed  bool
}

func authorize(session Session, token Confirmation, action, objectID string, now time.Time) (bool, string) {
	if token.Consumed {
		return false, "confirmation_already_consumed"
	}
	if now.After(token.ExpiresAt) {
		return false, "confirmation_expired"
	}
	if token.Subject != session.Subject || token.Tenant != session.Tenant {
		return false, "identity_scope_mismatch"
	}
	if token.Action != action || token.ObjectID != objectID {
		return false, "proposal_changed"
	}
	return true, "authorized"
}

func main() {
	now := time.Date(2026, time.October, 4, 10, 0, 0, 0, time.UTC)
	session := Session{Subject: "user-42", Tenant: "tenant-a"}
	token := Confirmation{
		ID:        "confirm-7",
		Subject:   "user-42",
		Tenant:    "tenant-a",
		Action:    "order.approve",
		ObjectID:  "order-9",
		Amount:    12500,
		ExpiresAt: now.Add(5 * time.Minute),
	}

	allowed, reason := authorize(session, token, "order.approve", "order-9", now)
	fmt.Printf("allowed=%t reason=%s amount=%d\n", allowed, reason, token.Amount)
}

Expected output:

text
allowed=true reason=authorized amount=12500

The production handler must consume the token atomically with an idempotency key and store the outcome. If the downstream call times out after execution, return outcome_unknown until reconciliation proves whether the effect occurred.

Sandbox and CSP: Strong Isolation, Incomplete Trust

The stable specification requires Hosts to render HTML Views in a sandbox and construct CSP from declared origins. If CSP metadata is omitted, the specified default denies external connections and nested frames while limiting other resource types.

This boundary reduces direct access to the Host DOM, cookies, and storage. It does not prove:

  • that UI text is honest or non-deceptive;
  • that an external origin is safe because it was declared;
  • that a Tool call is authorized;
  • that a returned object belongs to the current tenant;
  • that an action is reversible or exactly once;
  • that the interface is accessible.

Hosts may further restrict requested capabilities. Apps must not assume camera, microphone, geolocation, clipboard, open-link, or Tool-call access will be granted.

Progressive Enhancement and Compatibility

Host support varies. Maintain a compatibility matrix:

text
MCP core revision
x Apps extension revision
x SDK revision
x Host and version
x browser engine
x authentication profile
x supported capabilities

Test at least:

  • Host without Apps support receives a useful text fallback;
  • unknown UI fields and components are rejected safely;
  • deprecated metadata does not silently change behavior;
  • Resource fetches are bounded and use the expected MIME type;
  • CSP and permissions are no broader than declared;
  • app-only Tools are not exposed to the model;
  • unsupported requests produce explicit protocol errors;
  • teardown cancels subscriptions and releases resources.

"Works with MCP" is not a sufficient compatibility statement.

Accessibility and User Trust

An iframe is still a user interface. Test keyboard access, focus entry and return, accessible names, status announcements, zoom, reflow, contrast, localization, right-to-left layouts, and reduced motion. Preserve product-owned navigation and clearly distinguish generated or third-party content.

Sensitive actions need a fixed confirmation surface controlled by the Host or product. Do not let an App choose the trusted product name, amount, destination, permission scope, or confirmation wording.

Distribution, Billing, and Support Are Separate Systems

MCP Apps does not create an app store. Catalog and commercial layers still need:

  • publisher identity and ownership evidence;
  • version pinning and artifact provenance;
  • permission review and credential isolation;
  • vulnerability response and revocation;
  • install, upgrade, rollback, uninstall, and deletion;
  • metering rules for retries, cancellations, and duplicate delivery;
  • customer-visible evidence and dispute handling.

Measure successful user outcomes, not View renders or Tool-call count. A visually rich App with high retry rates, inaccessible controls, or unclear effects is not a successful product.

Release Checklist

  • [ ] Pin the core and Apps extension revisions.
  • [ ] Negotiate support and provide a non-UI fallback.
  • [ ] Use _meta.ui.resourceUri and the required MIME type.
  • [ ] Minimize model content and View structuredContent.
  • [ ] Declare the smallest CSP and permission set.
  • [ ] Keep identity, object authorization, price, and ownership server-side.
  • [ ] Bind confirmation and idempotency to the exact effect.
  • [ ] Test app-only Tool visibility and cross-server denial.
  • [ ] Test accessibility, localization, teardown, retries, and uncertain outcomes.
  • [ ] Publish a Host compatibility and rollback matrix.

Frequently Asked Questions

What is an MCP App?

It is an interactive UI delivered by an MCP Server through the official UI extension. A supporting Host renders the referenced ui:// HTML Resource and mediates communication with the View.

Are MCP Apps part of core MCP?

They are an official optional extension. Clients and Servers negotiate support, so graceful text or structured-data fallback remains necessary.

Does the iframe sandbox make an App secure?

It provides strong isolation from the Host, but the Host and Server still own CSP, capabilities, authentication, object authorization, confirmation, idempotency, and UI trust.

Can an App call every connected Tool?

No. Calls are mediated by the Host, constrained by Tool visibility and Host policy, and independently authorized by the Server.

Is MCP Apps an app store or billing protocol?

No. It standardizes interactive UI delivery and communication. Catalog, installation, publisher trust, billing, support, revocation, and deletion remain separate.

Primary Sources