Skip to content

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:

ExtensionIdentifierPrimary Purpose
MCP Appsio.modelcontextprotocol/uiInteractive graphical interfaces (dashboards, forms, charts) rendered in sandboxed iframes
Tasksio.modelcontextprotocol/tasksAsynchronous, long-running operations with durable task handles, polling, and mid-flight inputs
Skillsio.modelcontextprotocol/skillsDiscover and read reusable Agent Skills and supporting files via MCP resources
OAuth Client Credentialsio.modelcontextprotocol/oauth-client-credentialsMachine-to-machine authentication without interactive user prompts
Enterprise Authio.modelcontextprotocol/enterprise-managed-authorizationCentralized 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.

mermaid
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 sides

Client Declaration ​

The client declares supported extensions in _meta["io.modelcontextprotocol/clientCapabilities"].extensions with each request:

json
{
  "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:

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:

json
{
  "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:

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:

  1. A UI Resource: An HTML document served with MIME type text/html;profile=mcp-app (mcp.MIME_TYPE_MCP_APP).
  2. A Tool with _meta.ui: A tool whose definition contains _meta.ui.resourceUri pointing 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 ToolResult with _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:

zig
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:

zig
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():

zig
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 ​

StateDescription
workingThe operation is actively executing in the background
input_requiredThe server paused execution and requires client or human input (inputRequests)
completedThe task finished successfully; final output is in the result field
failedAn error occurred during execution; details are in the error field
cancelledThe task was cancelled via tasks/cancel

Server Setup for Tasks ​

zig
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/list to inspect available skills, YAML frontmatter, and file manifests.
  • Retrieval: Individual skills are fetched using skills/get with their canonical skill:// 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.content alongside 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.