MCP PHP SDK

Protocol Extensions

MCP protocol extensions advertise additional, optional capabilities during the initialize handshake. A server opts in via Builder::enableExtension() :

use Mcp\Schema\Extension\Apps\McpApps;
use Mcp\Server;

$server = Server::builder()
    ->setServerInfo('My Server', '1.0.0')
    ->enableExtension(new McpApps())
    ->build();

Pass one or more ServerExtensionInterface instances; multiple extensions can be enabled in a single call. Enabling the same extension twice throws a LogicException .

Note: extensions enabled via enableExtension() are merged into the extensions capability even when you supply your own ServerCapabilities via setCapabilities() . An enabled extension overrides any entry under the same id already present in those capabilities.

MCP Apps (io.modelcontextprotocol/ui )

The MCP Apps extension lets servers expose interactive HTML UIs as resources. Clients that support it render them in sandboxed iframes and bridge tool calls between the iframe (the View ) and the server via the host.

A UI consists of two pieces wired together by _meta.ui :

  1. A resource with URI scheme ui:// and MIME type text/html;profile=mcp-app , returning the HTML body.
  2. A tool linked to that resource via UiToolMeta , so the client knows to open the UI when the tool is invoked.
use Mcp\Schema\Content\TextResourceContents;
use Mcp\Schema\Extension\Apps\McpApps;
use Mcp\Schema\Extension\Apps\ToolVisibility;
use Mcp\Schema\Extension\Apps\UiResourceContentMeta;
use Mcp\Schema\Extension\Apps\UiResourceCsp;
use Mcp\Schema\Extension\Apps\UiResourcePermissions;
use Mcp\Schema\Extension\Apps\UiToolMeta;

$server = Server::builder()
    ->enableExtension(new McpApps())
    ->addResource(
        fn () => new TextResourceContents(
            uri: 'ui://my-app',
            mimeType: McpApps::MIME_TYPE,
            text: file_get_contents(__DIR__.'/app.html'),
            meta: ['ui' => new UiResourceContentMeta(
                csp: new UiResourceCsp(connectDomains: ['https://api.example.com']),
                permissions: new UiResourcePermissions(geolocation: true),
                prefersBorder: true,
            )],
        ),
        'ui://my-app',
        mimeType: McpApps::MIME_TYPE,
        meta: ['ui' => McpApps::resourceMarker()],
    )
    ->addTool(
        $myToolHandler,
        'my_tool',
        meta: ['ui' => new UiToolMeta(
            resourceUri: 'ui://my-app',
            visibility: [ToolVisibility::Model, ToolVisibility::App],
        )],
    )
    ->build();

Note the two distinct _meta.ui shapes: the resource descriptor (its resources/list entry) carries only an empty marker — McpApps::resourceMarker() — flagging it as an MCP App, while the resource content returned by resources/read carries the structured UiResourceContentMeta with the actual CSP and permission configuration.

Server-side DTOs

Class Purpose
McpApps Extension marker; provides EXTENSION_ID , MIME_TYPE , URI_SCHEME constants.
UiToolMeta Tool _meta.ui payload: resourceUri + visibility .
ToolVisibility Enum: Model , App .
UiResourceContentMeta Resource content _meta.ui : csp , permissions , domain , prefersBorder .
UiResourceCsp CSP allow-lists: connectDomains , resourceDomains , frameDomains , baseUriDomains .
UiResourcePermissions Sandbox permissions: camera , microphone , geolocation , clipboardWrite .

Writing the HTML view

The View and host exchange JSONRPCMessage objects (not JSON strings) via window.parent.postMessage . Before the host forwards tools/call , tool-input , or tool-result , the View must complete the spec-mandated handshake:

  1. View → Host: ui/initialize request
  2. Host → View: response with hostCapabilities , hostInfo , hostContext
  3. View → Host: ui/notifications/initialized
  4. View → Host: ui/notifications/size-changed whenever the iframe wants to resize

See the ext-apps repository for the full protocol, official TypeScript SDK (@modelcontextprotocol/ext-apps ), and view-side examples. A working minimal view is included in examples/server/mcp-apps/weather-app.html .

Search results