> ## Documentation Index
> Fetch the complete documentation index at: https://sunpeak.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP 2026-07-28 for MCP Apps
> Compatibility guide for MCP Apps on the MCP 2026-07-28 protocol: stateless requests, server/discover, required HTTP headers, caching, MRTR, and the unchanged ui/initialize View handshake.
MCP Apps SDK
MCP `2026-07-28` is the current core protocol revision. It replaces the Host-to-server handshake and protocol session with self-contained requests. The stable MCP Apps View protocol remains `2026-01-26` and still uses `ui/initialize` between the View and Host.
Those are separate protocol layers, so updating an MCP server does not remove the View handshake.
## Version Status
| Layer | Current standard | Current sunpeak |
| - | - | - |
| Host ↔ MCP server | Core MCP `2026-07-28` | Core MCP `2025-11-25` through the SDK 2.0 legacy compatibility transport |
| View ↔ Host | MCP Apps `2026-01-26` | MCP Apps `2026-01-26` through `@modelcontextprotocol/ext-apps` v2.0 |
sunpeak's `--stateless` option creates a fresh MCP server for each HTTP request, but it does
not enable the `2026-07-28` wire protocol. A server can be stateless at the application or
transport layer while still speaking the handshake-based `2025-11-25` revision.
The MCP TypeScript SDK implements the 2026 revision in its v2 API, and `@modelcontextprotocol/ext-apps@2.0.3` uses those split packages. Current sunpeak releases use ext-apps 2.0 and the client, core, and server 2.3 package line for their Views, inspector client, and server helpers. The framework's public HTTP wrappers still use the SDK's legacy Streamable HTTP transport, so a separate server-routing change is required before sunpeak can advertise the modern wire protocol. See the [MCP Apps SDK 2.0 Migration Guide](/docs/mcp-apps/sdk-v2-migration) for package and TypeScript API changes.
## What Changed in Core MCP
### Requests replace the protocol session
Core MCP `2026-07-28` removes `initialize`, `notifications/initialized`, and the `Mcp-Session-Id` header. Each request carries its protocol version and client capabilities in `_meta`. Clients should also send their identity with the request.
Servers must implement `server/discover`, which returns supported protocol versions, capabilities, identity, and optional instructions. A client may call it before other methods, but it can instead send its preferred version and retry after an `UnsupportedProtocolVersionError`.
This change applies only to the Host ↔ server connection. An MCP App View still calls `app.connect()`, which sends `ui/initialize` and `ui/notifications/initialized` over `postMessage`.
### HTTP requests are routable without reading the body
Streamable HTTP requests for the 2026 revision include:
* `MCP-Protocol-Version` with the requested protocol revision.
* `Mcp-Method` with the JSON-RPC method, such as `tools/call`.
* `Mcp-Name` with `params.name` for `tools/call` and `prompts/get`, or `params.uri` for `resources/read`.
Servers must reject a request when these headers disagree with the JSON-RPC body. Gateways can use them for routing and authorization without parsing the body.
### Lists and resource reads are cacheable
Completed results for `server/discover`, list methods, and `resources/read` include `ttlMs` and `cacheScope`. Use `cacheScope: "public"` only when every authorization context receives the same result. User-specific tool lists, resource lists, and UI resource HTML need `"private"` caching.
This matters for MCP App resources because a Host may cache the `ui://` HTML returned by `resources/read`. Keep user data in tool results or app-only requests, not in a publicly cacheable View template.
### OAuth authorization is stricter
Clients validate the authorization response's `iss` parameter before redeeming a code and keep
persisted credentials bound to the authorization server issuer. Dynamic Client Registration now
requires the client to send an appropriate `application_type`; it is deprecated in favor of Client
ID Metadata Documents and kept for backwards compatibility.
These rules apply to the Host-to-server connection. The View still calls tools through the Host and
should never receive the MCP access token. See [MCP OAuth Authorization for MCP
Apps](/docs/mcp-apps/mcp/authorization) for the complete flow and server checklist.
### Server-to-client requests use MRTR
Multi Round-Trip Requests (MRTR) replaces standalone server-to-client `sampling/createMessage`, `elicitation/create`, and `roots/list` requests. A tool that needs more input returns `resultType: "input_required"`; the client retries the original call with `inputResponses` and any opaque `requestState`.
The View method [`createSamplingMessage()`](/docs/mcp-apps/app/requests/create-sampling-message) is part of the MCP Apps protocol and still sends `sampling/createMessage` from the View to the Host. It is not the removed core server-to-client request path.
### Results and subscriptions changed
* Every result includes `resultType`, normally `"complete"`.
* `structuredContent` may be any JSON value when its `outputSchema` permits it. See [MCP structuredContent, content, and \_meta](/docs/mcp-apps/server/content-structuredcontent-meta#json-values-and-protocol-versions) for legacy and MCP Apps compatibility.
* `subscriptions/listen` replaces the HTTP GET notification stream and `resources/subscribe` methods.
* Tasks moved from the core protocol to the `io.modelcontextprotocol/tasks` extension.
* Core Roots, Sampling, and Logging are deprecated for new implementations. Their MCP Apps counterparts follow the Apps specification, not the deprecated core server APIs.
## MCP Apps Capability Detection
The UI extension identifier and settings stay the same:
```json theme={null}
{
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
}
```
In a legacy `2025-11-25` connection, the Host sends this object in the `initialize` request's client capabilities. In a modern `2026-07-28` connection, client capabilities travel in each request's `_meta`, and `server/discover` returns server capabilities.
Tool-to-View linkage does not change. A UI tool still points to a `ui://` resource with `_meta.ui.resourceUri`, and the resource still uses `text/html;profile=mcp-app`.
## Compatibility Matrix
| MCP server | sunpeak inspector and test client | 2026-capable Host |
| - | - | - |
| Legacy `2025-11-25` | Supported through automatic fallback | Supported when the Host can fall back to the legacy era |
| Dual-era | Supported through the 2026 path or legacy fallback | Supported through the 2026 path or legacy fallback |
| Modern-only `2026-07-28` | Supported | Supported |
The sunpeak inspector and test client now use the SDK 2.0 client's automatic version negotiation. A modern-only server should still return a clear error when a separate legacy client sends `initialize`, because that client has no way to negotiate forward.
## Prepare a sunpeak App for the Modern Wire Protocol
You do not need to change View code for the new core revision. On the server side:
1. Do not use `extra.sessionId` as application state. Return explicit handles from tools and accept them in later tool arguments.
2. Keep UI templates free of user data so they can use a clear cache policy.
3. Classify every list and resource read as public or private before adding cache hints.
4. Keep OAuth client state and credentials bound to the authorization server issuer.
5. Keep tool handlers independent of in-memory connection state so any request can run on any instance.
6. Test a dual-era server with both 2025 and 2026 clients before dropping legacy support.
7. Upgrade the MCP SDK and MCP Apps SDK only when their supported version ranges overlap.
## Primary References
Per-request version negotiation, server discovery, and legacy compatibility.
Normative change list from `2025-11-25`.
Stable UI resource, metadata, and View protocol.
Compare core MCP, MCP Apps, SDK package, and app versions.
Package, schema, handler, and error changes in ext-apps 2.0.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.