Skip to content

docs: update client capabilities for MCP 2026-07-28 #752

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dawNotPoi wants to merge 1 commit into
base: main
Choose a base branch
from
+92 −42
Open

docs: update client capabilities for MCP 2026-07-28 #752

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 46 additions & 21 deletions specification/2026-01-26/apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1495,13 +1495,49 @@ Clients and servers negotiate MCP Apps support through the standard MCP extensio

#### Client (Host) Capabilities

Clients advertise MCP Apps support in the initialize request using the extension identifier `io.modelcontextprotocol/ui`:
Clients advertise MCP Apps support using the extension identifier `io.modelcontextprotocol/ui`.

For MCP protocol version [`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#meta), client capabilities are request-scoped. A client that supports MCP Apps MUST include the UI extension under `_meta["io.modelcontextprotocol/clientCapabilities"].extensions` on every request:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
},
"io.modelcontextprotocol/clientInfo": {
"name": "example-host",
"version": "1.0.0"
}
}
}
}
```

The server MUST evaluate this value for each request and MUST NOT infer capabilities from an earlier request.

For earlier MCP protocol versions that use initialization, clients advertise the same extension once in the `initialize` request:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"protocolVersion": "2025-11-25",
"capabilities": {
"extensions": {
"io.modelcontextprotocol/ui": {
Expand All @@ -1517,6 +1553,8 @@ Clients advertise MCP Apps support in the initialize request using the extension
}
```

These client-to-server messages are separate from the View-to-Host `ui/initialize` handshake. A View declares its capabilities in `params.appCapabilities`; a Host advertises MCP Apps support to the MCP server through the client capabilities shown above.

**Extension Settings:**

- `mimeTypes`: Array of supported content types (REQUIRED, e.g., `["text/html;profile=mcp-app"]`)
Expand All @@ -1528,36 +1566,23 @@ Future versions may add additional settings:

#### Server Behavior

Servers SHOULD check client capabilities before registering UI-enabled tools. The SDK provides the `getUiCapability` helper for this:
Servers SHOULD check the client capabilities associated with the current request before exposing UI-enabled tool metadata. For MCP `2026-07-28`, `clientCapabilities` below is `_meta["io.modelcontextprotocol/clientCapabilities"]` from that request; for earlier protocol versions, it is the value negotiated during initialization. The SDK provides the `getUiCapability` helper for this:

```typescript
import { getUiCapability, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";

const uiCap = getUiCapability(clientCapabilities);
if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
// Register tools with UI templates
server.registerTool("get_weather", {
description: "Get weather with interactive dashboard",
inputSchema: { /* ... */ },
_meta: {
ui: { resourceUri: "ui://weather-server/dashboard" }
}
});
} else {
// Register text-only version
server.registerTool("get_weather", {
description: "Get weather as text",
inputSchema: { /* ... */ }
// No UI metadata
});
}
const supportsUi =
uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE) ?? false;
```

When `supportsUi` is `true`, servers can include `_meta.ui.resourceUri` in tool definitions returned for the current request. Otherwise they should omit UI metadata and provide text-only behavior.

**Graceful Degradation:**

- Servers SHOULD provide text-only fallback behavior for all UI-enabled tools
- Tools MUST return meaningful content array even when UI is available
- Servers MAY register different tool variants based on host capabilities
- Servers MAY adapt tool metadata or results based on the current request's client capabilities

### Extensibility

Expand Down
67 changes: 46 additions & 21 deletions specification/draft/apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2182,13 +2182,49 @@ Clients and servers negotiate MCP Apps support through the standard MCP extensio

#### Client (Host) Capabilities

Clients advertise MCP Apps support in the initialize request using the extension identifier `io.modelcontextprotocol/ui`:
Clients advertise MCP Apps support using the extension identifier `io.modelcontextprotocol/ui`.

For MCP protocol version [`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28/basic/index#meta), client capabilities are request-scoped. A client that supports MCP Apps MUST include the UI extension under `_meta["io.modelcontextprotocol/clientCapabilities"].extensions` on every request:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
},
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
},
"io.modelcontextprotocol/clientInfo": {
"name": "example-host",
"version": "1.0.0"
}
}
}
}
```

The server MUST evaluate this value for each request and MUST NOT infer capabilities from an earlier request.

For earlier MCP protocol versions that use initialization, clients advertise the same extension once in the `initialize` request:

```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"protocolVersion": "2025-11-25",
"capabilities": {
"extensions": {
"io.modelcontextprotocol/ui": {
Expand All @@ -2204,6 +2240,8 @@ Clients advertise MCP Apps support in the initialize request using the extension
}
```

These client-to-server messages are separate from the View-to-Host `ui/initialize` handshake. A View declares its capabilities in `params.appCapabilities`; a Host advertises MCP Apps support to the MCP server through the client capabilities shown above.

**Extension Settings:**

- `mimeTypes`: Array of supported content types (REQUIRED, e.g., `["text/html;profile=mcp-app"]`)
Expand All @@ -2215,36 +2253,23 @@ Future versions may add additional settings:

#### Server Behavior

Servers SHOULD check client capabilities before registering UI-enabled tools. The SDK provides the `getUiCapability` helper for this:
Servers SHOULD check the client capabilities associated with the current request before exposing UI-enabled tool metadata. For MCP `2026-07-28`, `clientCapabilities` below is `_meta["io.modelcontextprotocol/clientCapabilities"]` from that request; for earlier protocol versions, it is the value negotiated during initialization. The SDK provides the `getUiCapability` helper for this:

```typescript
import { getUiCapability, RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";

const uiCap = getUiCapability(clientCapabilities);
if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) {
// Register tools with UI templates
server.registerTool("get_weather", {
description: "Get weather with interactive dashboard",
inputSchema: { /* ... */ },
_meta: {
ui: { resourceUri: "ui://weather-server/dashboard" }
}
});
} else {
// Register text-only version
server.registerTool("get_weather", {
description: "Get weather as text",
inputSchema: { /* ... */ }
// No UI metadata
});
}
const supportsUi =
uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE) ?? false;
```

When `supportsUi` is `true`, servers can include `_meta.ui.resourceUri` in tool definitions returned for the current request. Otherwise they should omit UI metadata and provide text-only behavior.

**Graceful Degradation:**

- Servers SHOULD provide text-only fallback behavior for all UI-enabled tools
- Tools MUST return meaningful content array even when UI is available
- Servers MAY register different tool variants based on host capabilities
- Servers MAY adapt tool metadata or results based on the current request's client capabilities

#### App (Guest UI) Capabilities

Expand Down