MCP Apps Protocol Versions and Compatibility

MCP Apps SDK MCP Apps use two protocol connections: the Host connects to the MCP server, then the View connects to the Host over postMessage. Each connection has its own protocol version. The core MCP lifecycle depends on the negotiated revision, while the MCP Apps connection has its own initialization handshake. This distinction matters when an app works as a normal MCP tool but its UI does not render, or when the View renders but a host-mediated feature is missing.

The Four Versions

Version	Example	Where it appears	What it controls
Core MCP protocol	Latest: `2026-07-28`; sunpeak 0.20.x: `2025-11-25`	Host ↔ MCP server requests	Tools, resources, transport, and core MCP capabilities
MCP Apps protocol	`2026-01-26`	View ↔ Host `ui/initialize`	View lifecycle, host context, app capabilities, and `ui/*` messages
MCP Apps SDK package	`@modelcontextprotocol/ext-apps@1.7.5`	`package.json`	The implementation and APIs your code uses
Your app version	`1.4.0`	`appInfo.version`	Your View’s identity, not protocol compatibility

The date-based protocol versions are independent. A Host can support a given core MCP version without supporting MCP Apps, and an MCP Apps-capable Host may expose only some optional View APIs.

The current MCP Apps SDK exports LATEST_PROTOCOL_VERSION as "2026-01-26". Use the SDK handshake instead of copying this string into View code.

Two Independent Protocol Layers

1. Host ↔ Server in sunpeak 0.20.x

The core MCP initialize request negotiates the core protocol version. An MCP Apps Host also advertises the UI extension under capabilities.extensions:

{
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "extensions": {
        "io.modelcontextprotocol/ui": {
          "mimeTypes": ["text/html;profile=mcp-app"]
        }
      }
    },
    "clientInfo": {
      "name": "example-host",
      "version": "1.0.0"
    }
  }
}

Servers should check this extension before returning MCP Apps metadata. getUiCapability() reads the extension without tying your server to a specific Host name. Core MCP 2026-07-28 removes this handshake and carries the version, identity, and capabilities on each request. sunpeak 0.20.x uses the v1 MCP SDK and does not yet speak that modern wire protocol. See MCP 2026-07-28 for MCP Apps for the compatibility boundary and migration checklist.

2. View ↔ Host

The View performs a separate MCP Apps handshake over the iframe’s postMessage transport. The App class sends ui/initialize, reads the negotiated result, then sends ui/notifications/initialized.

import { App } from '@modelcontextprotocol/ext-apps';

const app = new App(
  { name: 'OrdersView', version: '1.4.0' },
  { availableDisplayModes: ['inline', 'fullscreen'] }
);

app.ontoolresult = (result) => {
  renderOrders(result.structuredContent);
};

await app.connect();

appInfo.version identifies this View build. It does not select the MCP Apps protocol version. App.connect() handles that protocol detail.

Capability Checks Still Matter

Matching protocol versions do not mean every optional feature is available. Check the capabilities returned by the Host before showing controls that depend on them:

await app.connect();

const capabilities = app.getHostCapabilities();

const canCallTools = Boolean(capabilities?.serverTools);
const canReadResources = Boolean(capabilities?.serverResources);
const canSendText = Boolean(capabilities?.message?.text);
const canDownload = Boolean(capabilities?.downloadFile);
const canSample = Boolean(capabilities?.sampling);

Use feature checks instead of Host-name checks. A Host can add capabilities without changing its name, and two versions of the same Host may support different features.

Compatibility Rules

Use App.connect() for Views and AppBridge for Hosts so the SDK handles MCP Apps version negotiation.
Use getUiCapability() before registering UI-enabled server tools.
Keep meaningful text in tool result content so clients without MCP Apps support still work.
Treat Host capabilities as feature gates for server tools, resources, messages, sampling, downloads, and links.
Register one-shot View handlers, including ontoolinput and ontoolresult, before connect().
Use _meta.ui.resourceUri for tool-to-View linkage. The flat _meta["ui/resourceUri"] key exists only for compatibility with older Hosts.
Upgrade the core MCP SDK and MCP Apps SDK together when their peer dependency ranges require it.

Diagnose a Version or Capability Mismatch

Symptom	Check
Tool works, but no View appears	Confirm the Host advertised `io.modelcontextprotocol/ui`, the tool has `_meta.ui.resourceUri`, and the resource uses `text/html;profile=mcp-app`.
View iframe appears, but stays blank or hidden	Confirm `app.connect()` completes and no host-bound method runs before the `ui/initialize` handshake.
A View button fails to call a server tool	Check `hostCapabilities.serverTools` and make sure the tool’s visibility includes `"app"`.
A View API works in one Host only	Compare `getHostCapabilities()` results and add a disabled state or fallback for the missing feature.
Protocol validation fails after an upgrade	Check the installed `@modelcontextprotocol/ext-apps` and `@modelcontextprotocol/sdk` versions, then compare the payload with the SDK’s exported schemas.

Primary References

MCP Apps 2026-01-26 Specification

Stable extension specification for resources, metadata, lifecycle, and View messages.

Core MCP 2026-07-28 Versioning

Current per-request version negotiation and legacy compatibility.

MCP 2026-07-28 for MCP Apps

What the stateless core revision changes for servers and what stays the same for Views.

Protocol Reference

MCP Apps types, schemas, method constants, and current SDK protocol constant.

Capability Detection

Server-side detection and text fallback pattern.

Overview

App

MCP

React

Server

Styling

Types

MCP Apps Protocol Versions and Compatibility

The Four Versions

Two Independent Protocol Layers

1. Host ↔ Server in sunpeak 0.20.x

2. View ↔ Host

Capability Checks Still Matter

Compatibility Rules

Diagnose a Version or Capability Mismatch

Primary References

MCP Apps 2026-01-26 Specification

Core MCP 2026-07-28 Versioning

MCP 2026-07-28 for MCP Apps

Protocol Reference

Capability Detection

​The Four Versions

​Two Independent Protocol Layers

​1. Host ↔ Server in sunpeak 0.20.x

​2. View ↔ Host

​Capability Checks Still Matter

​Compatibility Rules

​Diagnose a Version or Capability Mismatch

​Primary References

MCP Apps 2026-01-26 Specification

Core MCP 2026-07-28 Versioning

MCP 2026-07-28 for MCP Apps

Protocol Reference

Capability Detection

The Four Versions

Two Independent Protocol Layers

1. Host ↔ Server in sunpeak 0.20.x

2. View ↔ Host

Capability Checks Still Matter

Compatibility Rules

Diagnose a Version or Capability Mismatch

Primary References