MCP Extensions & Apps β
MCP extensions are modular capabilities beyond the core 2026-07-28 specification. They allow servers and clients to negotiate rich featuresβsuch as interactive HTML applications, asynchronous task execution, and agent skillsβwhile preserving graceful degradation for standard clients.
Overview of Official Extensions β
Extensions use reverse-domain vendor prefixed identifiers. The official MCP extensions live under the io.modelcontextprotocol namespace:
| Extension | Identifier | Primary Purpose |
|---|---|---|
| MCP Apps | io.modelcontextprotocol/ui | Interactive graphical interfaces (dashboards, forms, charts) rendered in sandboxed iframes |
| Tasks | io.modelcontextprotocol/tasks | Asynchronous, long-running operations with durable task handles, polling, and mid-flight inputs |
| Skills | io.modelcontextprotocol/skills | Discover and read reusable Agent Skills and supporting files via MCP resources |
| OAuth Client Credentials | io.modelcontextprotocol/oauth-client-credentials | Machine-to-machine authentication without interactive user prompts |
| Enterprise Auth | io.modelcontextprotocol/enterprise-managed-authorization | Centralized corporate SSO and identity provider (IdP) authorization |
Extension Negotiation β
Extensions in MCP are strictly opt-in. Neither server nor client enables extension-specific behavior unless both declare support during capability exchange.
sequenceDiagram
participant Client as MCP Client
participant Server as MCP Server
Client->>Server: server/discover (with clientCapabilities.extensions in _meta)
Server-->>Client: capabilities.extensions (advertised server extensions)
Note over Client,Server: Extensions active only if supported by both sidesClient Declaration β
The client declares supported extensions in _meta["io.modelcontextprotocol/clientCapabilities"].extensions with each request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "open_dashboard",
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
}
}
}
}In Zig:
var client = mcp.Client.init(allocator, .{
.name = "MyClient",
.version = "1.0.0",
});
defer client.deinit();
// Advertise support for MCP Apps UI extension
try client.enableUi();Server Declaration β
The server advertises supported extensions in its server/discover response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2026-07-28",
"supportedVersions": ["2026-07-28"],
"capabilities": {
"tools": {},
"resources": {},
"extensions": {
"io.modelcontextprotocol/ui": {}
}
},
"resultType": "complete"
}
}In Zig:
var server = mcp.Server.init(allocator, .{
.name = "MyServer",
.version = "1.0.0",
});
defer server.deinit();
// Advertise support for MCP Apps UI extension
try server.enableUi();MCP Apps (io.modelcontextprotocol/ui) β
MCP Apps allow servers to return rich, interactive HTML interfaces that render directly inside host applications (such as Claude Desktop, Zed, Goose, or custom web portals).
How MCP Apps Work β
Traditional MCP tools return text, markdown, or structured JSON. MCP Apps extend this by pairing two primitives:
- A UI Resource: An HTML document served with MIME type
text/html;profile=mcp-app(mcp.MIME_TYPE_MCP_APP). - A Tool with
_meta.ui: A tool whose definition contains_meta.ui.resourceUripointing to the UI resource URI.
When an AI host invokes or preloads the tool:
- The host reads the UI resource from the server via
resources/read. - The host renders the HTML inside a sandboxed
<iframe>. - The tool call execution returns a
ToolResultwith_meta.ui.resourceUri, which the host immediately routes to the active iframe. - The embedded app communicates with the host via JSON-RPC over
postMessage.
Defining UI Resources β
Use mcp.ResourceBuilder with .mcpApp() to expose UI resources:
var dash_builder = mcp.ResourceBuilder.init("ui://dashboard/interactive", "Dashboard");
_ = dash_builder
.title("Interactive System Dashboard")
.description("Live interactive metrics and control panel")
.mcpApp() // sets MIME type to text/html;profile=mcp-app
.handler(dashboardHandler);
try server.addResource(dash_builder.build());Linking Tools to UI β
Use ToolBuilder.ui() or ToolBuilder.uiWithVisibility() to attach UI metadata to a tool:
var tool_builder = mcp.ToolBuilder.init("open_dashboard");
_ = try tool_builder
.title("Open Interactive Dashboard")
.description("Launches the real-time system metrics interface")
.readOnly()
.idempotent()
.ui(allocator, "ui://dashboard/interactive");
_ = tool_builder.handler(openDashboardHandler);
try server.addTool(tool_builder.build());In the handler, return a ToolResult carrying UI metadata using mcp.uiResult():
fn openDashboardHandler(
_: ?*anyopaque,
_: std.Io,
allocator: std.mem.Allocator,
_: ?std.json.Value,
) mcp.tools.ToolError!mcp.ToolResult {
return mcp.uiResult(
allocator,
"ui://dashboard/interactive",
"Dashboard ready. The interactive interface is active in your viewport.",
) catch return mcp.tools.ToolError.OutOfMemory;
}Working Example β
See the complete runnable server in examples/mcp_app_server.zig and its documentation in MCP Apps Server Example.
MCP Tasks (io.modelcontextprotocol/tasks) β
The Tasks extension decouples long-running operations from synchronous request timeouts. Instead of blocking the connection, the server creates a durable task handle and returns a CreateTaskResult with resultType: "task".
Task States β
| State | Description |
|---|---|
working | The operation is actively executing in the background |
input_required | The server paused execution and requires client or human input (inputRequests) |
completed | The task finished successfully; final output is in the result field |
failed | An error occurred during execution; details are in the error field |
cancelled | The task was cancelled via tasks/cancel |
Server Setup for Tasks β
var server = mcp.Server.init(allocator, .{
.name = "task-server",
.version = "1.0.0",
});
defer server.deinit();
// Enables task management endpoints (tasks/get, tasks/update, tasks/cancel)
try server.enableTasks();Skills over MCP (io.modelcontextprotocol/skills) β
The Skills extension allows servers to publish reusable Agent Skills with SKILL.md instructions and supporting reference files over MCP.
- Discovery: Clients query
skills/listto inspect available skills, YAML frontmatter, and file manifests. - Retrieval: Individual skills are fetched using
skills/getwith their canonicalskill://URI. - Execution: Skill instructions and supporting files are retrieved on demand using standard
resources/read.
Graceful Degradation β
If a connected client does not declare support for an extension:
- UI Tools: Fall back gracefully by delivering clear text content in
ToolResult.contentalongside the optional_meta.ui. - Tasks: Complete operations synchronously when possible, or return standard JSON-RPC errors when long-running background tasks cannot proceed without client polling.
