feat: add MCP Apps extension (io.modelcontextprotocol/ui) support

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: chr-hertel

composer.json

@@ -76,6 +76,7 @@
       "Mcp\\Example\\Server\\DiscoveryUserProfile\\": "examples/server/discovery-userprofile/",
       "Mcp\\Example\\Server\\EnvVariables\\": "examples/server/env-variables/",
       "Mcp\\Example\\Server\\ExplicitRegistration\\": "examples/server/explicit-registration/",
+      "Mcp\\Example\\Server\\McpApps\\": "examples/server/mcp-apps/",
       "Mcp\\Example\\Server\\OAuthKeycloak\\": "examples/server/oauth-keycloak/",
       "Mcp\\Example\\Server\\OAuthMicrosoft\\": "examples/server/oauth-microsoft/",
       "Mcp\\Example\\Server\\SchemaShowcase\\": "examples/server/schema-showcase/",
@@ -89,4 +90,4 @@
     },
     "sort-packages": true
   }
-}
+}

examples/server/mcp-apps/WeatherApp.php

@@ -0,0 +1,62 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Example\Server\McpApps;
+
+use Mcp\Schema\Content\TextResourceContents;
+use Mcp\Schema\Extension\Apps\McpApps;
+use Mcp\Schema\Extension\Apps\UiResourceContentMeta;
+use Mcp\Schema\Extension\Apps\UiResourceCsp;
+use Mcp\Schema\Extension\Apps\UiResourcePermissions;
+
+final class WeatherApp
+{
+    public function getWeatherApp(): TextResourceContents
+    {
+        $contentMeta = new UiResourceContentMeta(
+            csp: new UiResourceCsp(
+                connectDomains: ['https://api.weather.example.com'],
+            ),
+            permissions: new UiResourcePermissions(
+                geolocation: true,
+            ),
+            prefersBorder: true,
+        );
+
+        return new TextResourceContents(
+            uri: 'ui://weather-app',
+            mimeType: McpApps::MIME_TYPE,
+            text: file_get_contents(__DIR__.'/weather-app.html'),
+            meta: ['ui' => $contentMeta],
+        );
+    }
+
+    public function getWeather(string $city): string
+    {
+        $weather = [
+            'london' => ['temp' => '15°C', 'condition' => 'Cloudy', 'humidity' => '78%'],
+            'paris' => ['temp' => '18°C', 'condition' => 'Sunny', 'humidity' => '55%'],
+            'tokyo' => ['temp' => '22°C', 'condition' => 'Partly Cloudy', 'humidity' => '65%'],
+            'new york' => ['temp' => '12°C', 'condition' => 'Rainy', 'humidity' => '85%'],
+        ];
+
+        $key = strtolower($city);
+        $data = $weather[$key] ?? ['temp' => '20°C', 'condition' => 'Clear', 'humidity' => '60%'];
+
+        return \sprintf(
+            'Weather in %s: %s, %s, Humidity: %s',
+            $city,
+            $data['temp'],
+            $data['condition'],
+            $data['humidity'],
+        );
+    }
+}

examples/server/mcp-apps/server.php

@@ -0,0 +1,51 @@
+#!/usr/bin/env php
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require_once dirname(__DIR__).'/bootstrap.php';
+chdir(__DIR__);
+
+use Mcp\Example\Server\McpApps\WeatherApp;
+use Mcp\Schema\Enum\ToolVisibility;
+use Mcp\Schema\Extension\Apps\McpApps;
+use Mcp\Schema\Extension\Apps\UiToolMeta;
+use Mcp\Server;
+
+logger()->info('Starting MCP Apps Example Server...');
+
+$server = Server::builder()
+    ->setServerInfo('MCP Apps Weather Example', '1.0.0')
+    ->setLogger(logger())
+    ->enableExtension(McpApps::class)
+    ->addResource(
+        [WeatherApp::class, 'getWeatherApp'],
+        'ui://weather-app',
+        'weather-app',
+        description: 'Interactive weather dashboard',
+        mimeType: McpApps::MIME_TYPE,
+        meta: ['ui' => []],
+    )
+    ->addTool(
+        [WeatherApp::class, 'getWeather'],
+        'get_weather',
+        description: 'Get current weather for a city',
+        meta: ['ui' => new UiToolMeta(
+            resourceUri: 'ui://weather-app',
+            visibility: [ToolVisibility::Model->value, ToolVisibility::App->value],
+        )],
+    )
+    ->build();
+
+$result = $server->run(transport());
+
+logger()->info('Server stopped gracefully.', ['result' => $result]);
+
+shutdown($result);

examples/server/mcp-apps/weather-app.html

@@ -0,0 +1,107 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Weather Dashboard</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            font-family: var(--font-sans, system-ui, sans-serif);
+            background: var(--color-background-primary, #ffffff);
+            color: var(--color-text-primary, #1a1a1a);
+            padding: 1rem;
+        }
+        .card {
+            border: 1px solid var(--color-border-primary, #e0e0e0);
+            border-radius: var(--border-radius-md, 8px);
+            padding: 1rem;
+            margin-bottom: 1rem;
+        }
+        h1 { font-size: var(--font-heading-md-size, 1.25rem); margin-bottom: 0.5rem; }
+        .weather-data { font-size: var(--font-text-lg-size, 1.125rem); }
+        button {
+            background: var(--color-background-info, #0066cc);
+            color: var(--color-text-inverse, #ffffff);
+            border: none;
+            border-radius: var(--border-radius-sm, 4px);
+            padding: 0.5rem 1rem;
+            cursor: pointer;
+            font-size: var(--font-text-md-size, 1rem);
+        }
+        input {
+            border: 1px solid var(--color-border-primary, #e0e0e0);
+            border-radius: var(--border-radius-sm, 4px);
+            padding: 0.5rem;
+            font-size: var(--font-text-md-size, 1rem);
+            margin-right: 0.5rem;
+        }
+    </style>
+</head>
+<body>
+    <div class="card">
+        <h1>Weather Dashboard</h1>
+        <div>
+            <input type="text" id="city" placeholder="Enter city name" value="London">
+            <button onclick="fetchWeather()">Get Weather</button>
+        </div>
+    </div>
+    <div class="card" id="result" style="display:none">
+        <div class="weather-data" id="weather-data"></div>
+    </div>
+    <script>
+        // MCP Apps communicate with the host via window.parent.postMessage
+        // using JSON-RPC 2.0 messages.
+        let requestId = 0;
+        const pending = new Map();
+
+        window.addEventListener('message', (event) => {
+            try {
+                const msg = JSON.parse(event.data);
+                if (msg.id && pending.has(msg.id)) {
+                    pending.get(msg.id)(msg);
+                    pending.delete(msg.id);
+                }
+                // Handle tool input notification
+                if (msg.method === 'ui/notifications/tool-input') {
+                    document.getElementById('city').value = msg.params.arguments.city || '';
+                }
+                // Handle tool result notification
+                if (msg.method === 'ui/notifications/tool-result') {
+                    displayResult(msg.params);
+                }
+            } catch (e) { /* ignore non-JSON messages */ }
+        });
+
+        function sendRpc(method, params) {
+            return new Promise((resolve) => {
+                const id = ++requestId;
+                pending.set(id, resolve);
+                window.parent.postMessage(JSON.stringify({
+                    jsonrpc: '2.0', id, method, params
+                }), '*');
+            });
+        }
+
+        async function fetchWeather() {
+            const city = document.getElementById('city').value;
+            const response = await sendRpc('tools/call', {
+                name: 'get_weather',
+                arguments: { city }
+            });
+            if (response.result) {
+                displayResult(response.result);
+            }
+        }
+
+        function displayResult(result) {
+            const el = document.getElementById('result');
+            const data = document.getElementById('weather-data');
+            if (result.content && result.content[0]) {
+                data.textContent = result.content[0].text;
+            }
+            el.style.display = 'block';
+        }
+    </script>
+</body>
+</html>

src/Schema/ClientCapabilities.php

@@ -20,14 +20,16 @@
 class ClientCapabilities implements \JsonSerializable
 {
     /**
-     * @param array<string, mixed> $experimental
+     * @param array<string, mixed>  $experimental
+     * @param ?array<string, mixed> $extensions   protocol extensions the client supports (e.g. io.modelcontextprotocol/ui)
      */
     public function __construct(
         public readonly ?bool $roots = false,
         public readonly ?bool $rootsListChanged = null,
         public readonly ?bool $sampling = null,
         public readonly ?bool $elicitation = null,
         public readonly ?array $experimental = null,
+        public readonly ?array $extensions = null,
     ) {
     }
 
@@ -39,6 +41,7 @@ public function __construct(
      *     sampling?: bool,
      *     elicitation?: bool,
      *     experimental?: array<string, mixed>,
+     *     extensions?: array<string, mixed>,
      * } $data
      */
     public static function fromArray(array $data): self
@@ -68,7 +71,8 @@ public static function fromArray(array $data): self
             $rootsListChanged,
             $sampling,
             $elicitation,
-            $data['experimental'] ?? null
+            $data['experimental'] ?? null,
+            $data['extensions'] ?? null,
         );
     }
 
@@ -78,6 +82,7 @@ public static function fromArray(array $data): self
      *     sampling?: object,
      *     elicitation?: object,
      *     experimental?: object,
+     *     extensions?: object,
      * }
      */
     public function jsonSerialize(): array
@@ -102,6 +107,10 @@ public function jsonSerialize(): array
             $data['experimental'] = (object) $this->experimental;
         }
 
+        if ($this->extensions) {
+            $data['extensions'] = (object) $this->extensions;
+        }
+
         return $data;
     }
 }

src/Schema/Enum/ToolVisibility.php

@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Schema\Enum;
+
+/**
+ * Tool visibility values for MCP Apps.
+ *
+ * Controls who can see and invoke a tool linked to a UI resource.
+ */
+enum ToolVisibility: string
+{
+    /** Visible to and callable by the LLM agent. */
+    case Model = 'model';
+
+    /** Callable by the MCP App (HTML view) only, hidden from the model's tools/list. */
+    case App = 'app';
+}

src/Schema/Extension/Apps/McpApps.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Schema\Extension\Apps;
+
+use Mcp\Schema\Extension\ServerExtensionInterface;
+use Mcp\Schema\Resource;
+
+/**
+ * The MCP Apps extension (io.modelcontextprotocol/ui).
+ *
+ * MCP Apps allows servers to expose interactive HTML UI applications as resources.
+ * Clients that support the extension render these in sandboxed iframes.
+ *
+ * Enable on the server via {@see \Mcp\Server\Builder::enableExtension()}.
+ *
+ * @see https://github.com/modelcontextprotocol/ext-apps
+ */
+final class McpApps implements ServerExtensionInterface
+{
+    public const EXTENSION_ID = 'io.modelcontextprotocol/ui';
+    public const MIME_TYPE = 'text/html;profile=mcp-app';
+    public const URI_SCHEME = 'ui';
+
+    public function getId(): string
+    {
+        return self::EXTENSION_ID;
+    }
+
+    /**
+     * @return array{mimeTypes: string[]}
+     */
+    public function getCapabilities(): array
+    {
+        return ['mimeTypes' => [self::MIME_TYPE]];
+    }
+
+    /**
+     * Checks whether a Resource is a UI resource based on its URI scheme and MIME type.
+     */
+    public static function isUiResource(Resource $resource): bool
+    {
+        return str_starts_with($resource->uri, self::URI_SCHEME.'://')
+            && self::MIME_TYPE === $resource->mimeType;
+    }
+}