feat(core): add extension() registrar for SEP-2133 capability-aware custom methods

Adds Client.extension(id, settings, {peerSchema?}) and Server.extension(...)
returning an ExtensionHandle that:
- merges settings into capabilities.extensions[id] (advertised in initialize)
- exposes getPeerSettings() with optional schema validation of the peer blob
- wraps setCustom*/sendCustom* with peer-capability gating under
  enforceStrictCapabilities

Connects the SEP-2133 capabilities.extensions field to the custom-method API
from #1846. Declare-before-register is structural (you cannot get a handle
without declaring); peer-gating on send mirrors assertCapabilityForMethod.

Stacked on #1846.

Author: felixweinberger

.changeset/extension-registrar.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/client': minor
+'@modelcontextprotocol/server': minor
+---
+
+Add `Client.extension()` / `Server.extension()` registrar for SEP-2133 capability-aware custom methods. Declares an extension in `capabilities.extensions[id]` and returns an `ExtensionHandle` whose `setRequestHandler`/`sendRequest`/`setNotificationHandler`/`sendNotification` calls are tied to that declared capability. `getPeerSettings()` returns the peer's extension settings, optionally validated against a `peerSchema`.

docs/migration.md

@@ -435,6 +435,36 @@ before sending and gives typed `params`; passing a bare result schema sends para
 For larger sub-protocols where neither side is semantically an MCP client or server, prefer composition: hold a `Client` (or `Server`) instance, register custom handlers on it, and expose typed facade methods. See `examples/server/src/customMethodExtAppsExample.ts` for a worked
 example.
 
+#### Declaring extension capabilities (SEP-2133)
+
+When your custom methods constitute a formal extension with an SEP-2133 identifier (e.g.
+`io.modelcontextprotocol/ui`), use `Client.extension()` / `Server.extension()` instead of the flat
+`*Custom*` methods. This declares the extension in `capabilities.extensions[id]` so it is
+negotiated during `initialize`, and returns a scoped `ExtensionHandle` whose `setRequestHandler` /
+`sendRequest` calls are tied to that declared capability:
+
+```typescript
+import { Client } from '@modelcontextprotocol/client';
+
+const client = new Client({ name: 'app', version: '1.0.0' });
+const ui = client.extension(
+    'io.modelcontextprotocol/ui',
+    { availableDisplayModes: ['inline'] },
+    { peerSchema: HostCapabilitiesSchema }
+);
+
+ui.setRequestHandler('ui/resource-teardown', TeardownParams, p => onTeardown(p));
+
+await client.connect(transport);
+ui.getPeerSettings(); // server's capabilities.extensions['io.modelcontextprotocol/ui'], typed via peerSchema
+await ui.sendRequest('ui/open-link', { url }, OpenLinkResult);
+```
+
+`handle.sendRequest`/`sendNotification` respect `enforceStrictCapabilities`: when strict, sending
+throws if the peer did not advertise the same extension ID. The flat `setCustomRequestHandler` /
+`sendCustomRequest` methods remain available as the ungated escape hatch for one-off vendor
+methods that do not warrant a SEP-2133 entry.
+
 
 ### `Protocol.request()`, `ctx.mcpReq.send()`, and `Client.callTool()` no longer take a schema parameter
 

examples/server/src/customMethodExtAppsExample.ts

@@ -1,32 +1,40 @@
 #!/usr/bin/env node
 /**
  * Demonstrates that the ext-apps (mcp-ui) pattern is fully implementable on top of the v2
- * SDK's custom-method-handler API, without extending Protocol or relying on the v1 generic
+ * SDK's `extension()` registrar, without extending Protocol or relying on the v1 generic
  * type parameters.
  *
  * In v1, ext-apps defined `class ProtocolWithEvents<...> extends Protocol<SendRequestT, ...>` to
- * widen the request/notification type unions. In v2, the same is achieved by composing
- * setCustomRequestHandler / setCustomNotificationHandler / sendCustomRequest / sendCustomNotification
- * on top of the standard Client and Server classes.
+ * widen the request/notification type unions. In v2, the same is achieved by composing a
+ * `Client`/`Server`, declaring an SEP-2133 extension via `.extension(id, settings)`, and using the
+ * returned `ExtensionHandle` for all `ui/*` methods. Capability negotiation happens via the
+ * standard MCP `initialize` exchange — no separate `ui/initialize` round-trip needed.
  */
 
-import { Client } from '@modelcontextprotocol/client';
+import { Client, type ExtensionHandle } from '@modelcontextprotocol/client';
 import { InMemoryTransport, Server } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 
+const EXT_ID = 'io.modelcontextprotocol/ui';
+
 // ───────────────────────────────────────────────────────────────────────────────
-// Custom method schemas (mirror the ext-apps spec.types.ts pattern)
+// SEP-2133 extension capability shapes (asymmetric — App and Host advertise different things)
 // ───────────────────────────────────────────────────────────────────────────────
 
-const InitializeParams = z.object({
-    protocolVersion: z.string(),
-    appInfo: z.object({ name: z.string(), version: z.string() })
+const AppCapabilities = z.object({
+    availableDisplayModes: z.array(z.enum(['inline', 'fullscreen']))
 });
-const InitializeResult = z.object({
-    protocolVersion: z.string(),
-    hostInfo: z.object({ name: z.string(), version: z.string() }),
+type AppCapabilities = z.infer<typeof AppCapabilities>;
+
+const HostCapabilities = z.object({
+    openLinks: z.boolean(),
     hostContext: z.object({ theme: z.enum(['light', 'dark']), locale: z.string() })
 });
+type HostCapabilities = z.infer<typeof HostCapabilities>;
+
+// ───────────────────────────────────────────────────────────────────────────────
+// Custom method schemas (mirror the ext-apps spec.types.ts pattern)
+// ───────────────────────────────────────────────────────────────────────────────
 
 const OpenLinkParams = z.object({ url: z.url() });
 const OpenLinkResult = z.object({ opened: z.boolean() });
@@ -43,32 +51,32 @@ type AppEventMap = {
 };
 
 // ───────────────────────────────────────────────────────────────────────────────
-// App: wraps Client, exposes typed mcp-ui/* methods + DOM-style events
+// App: wraps Client + ExtensionHandle, exposes typed mcp-ui/* methods + DOM-style events
 // (replaces v1's `class App extends ProtocolWithEvents<AppRequest, AppNotification, AppResult, AppEventMap>`)
 // ───────────────────────────────────────────────────────────────────────────────
 
 class App {
     readonly client: Client;
+    readonly ui: ExtensionHandle<AppCapabilities, HostCapabilities>;
     private _listeners: { [K in keyof AppEventMap]: ((p: AppEventMap[K]) => void)[] } = {
         toolresult: [],
         hostcontextchanged: []
     };
-    private _hostContext?: z.infer<typeof InitializeResult>['hostContext'];
+    private _hostContext?: HostCapabilities['hostContext'];
 
     onTeardown?: (params: z.infer<typeof TeardownParams>) => void | Promise<void>;
 
-    constructor(appInfo: { name: string; version: string }) {
+    constructor(appInfo: { name: string; version: string }, caps: AppCapabilities) {
         this.client = new Client(appInfo, { capabilities: {} });
+        this.ui = this.client.extension(EXT_ID, caps, { peerSchema: HostCapabilities });
 
-        // Incoming custom request from host
-        this.client.setCustomRequestHandler('mcp-ui/resourceTeardown', TeardownParams, async params => {
+        this.ui.setRequestHandler('mcp-ui/resourceTeardown', TeardownParams, async params => {
             await this.onTeardown?.(params);
             return {};
         });
 
-        // Incoming custom notifications from host -> DOM-style event slots
-        this.client.setCustomNotificationHandler('mcp-ui/toolResult', ToolResultParams, p => this._dispatch('toolresult', p));
-        this.client.setCustomNotificationHandler('mcp-ui/hostContextChanged', HostContextChangedParams, p => {
+        this.ui.setNotificationHandler('mcp-ui/toolResult', ToolResultParams, p => this._dispatch('toolresult', p));
+        this.ui.setNotificationHandler('mcp-ui/hostContextChanged', HostContextChangedParams, p => {
             this._hostContext = { ...this._hostContext!, ...p };
             this._dispatch('hostcontextchanged', p);
         });
@@ -89,77 +97,74 @@ class App {
     }
 
     async connect(transport: Parameters<Client['connect']>[0]): Promise<void> {
+        // MCP `initialize` carries capabilities.extensions[EXT_ID] both ways — no separate
+        // mcp-ui/initialize round-trip needed.
         await this.client.connect(transport);
-        const result = await this.client.sendCustomRequest(
-            'mcp-ui/initialize',
-            { protocolVersion: '2026-01-26', appInfo: { name: 'demo-app', version: '1.0.0' } },
-            InitializeResult
-        );
-        this._hostContext = result.hostContext;
-        await this.client.sendCustomNotification('mcp-ui/initialized', {});
+        this._hostContext = this.ui.getPeerSettings()?.hostContext;
+    }
+
+    get hostCapabilities(): HostCapabilities | undefined {
+        return this.ui.getPeerSettings();
     }
 
     getHostContext() {
         return this._hostContext;
     }
 
     openLink(url: string) {
-        return this.client.sendCustomRequest('mcp-ui/openLink', { url }, OpenLinkResult);
+        return this.ui.sendRequest('mcp-ui/openLink', { url }, OpenLinkResult);
     }
 
     notifySizeChanged(width: number, height: number) {
-        return this.client.sendCustomNotification('mcp-ui/sizeChanged', { width, height });
+        return this.ui.sendNotification('mcp-ui/sizeChanged', { width, height });
     }
 }
 
 // ───────────────────────────────────────────────────────────────────────────────
-// Host: wraps Server, handles mcp-ui/* requests and emits mcp-ui/* notifications
+// Host: wraps Server + ExtensionHandle, handles mcp-ui/* requests and emits mcp-ui/* notifications
 // ───────────────────────────────────────────────────────────────────────────────
 
 class Host {
     readonly server: Server;
+    readonly ui: ExtensionHandle<HostCapabilities, AppCapabilities>;
     onSizeChanged?: (p: z.infer<typeof SizeChangedParams>) => void;
 
     constructor() {
         this.server = new Server({ name: 'demo-host', version: '1.0.0' }, { capabilities: {} });
+        this.ui = this.server.extension(
+            EXT_ID,
+            { openLinks: true, hostContext: { theme: 'dark', locale: 'en-US' } },
+            { peerSchema: AppCapabilities }
+        );
 
-        this.server.setCustomRequestHandler('mcp-ui/initialize', InitializeParams, params => {
-            console.log(`[host] mcp-ui/initialize from ${params.appInfo.name}@${params.appInfo.version}`);
-            return {
-                protocolVersion: params.protocolVersion,
-                hostInfo: { name: 'demo-host', version: '1.0.0' },
-                hostContext: { theme: 'dark', locale: 'en-US' }
-            };
-        });
-
-        this.server.setCustomRequestHandler('mcp-ui/openLink', OpenLinkParams, params => {
+        this.ui.setRequestHandler('mcp-ui/openLink', OpenLinkParams, params => {
             console.log(`[host] mcp-ui/openLink url=${params.url}`);
             return { opened: true };
         });
 
-        this.server.setCustomNotificationHandler('mcp-ui/initialized', z.object({}).optional(), () => {
-            console.log('[host] mcp-ui/initialized');
-        });
-
-        this.server.setCustomNotificationHandler('mcp-ui/sizeChanged', SizeChangedParams, p => {
+        this.ui.setNotificationHandler('mcp-ui/sizeChanged', SizeChangedParams, p => {
             console.log(`[host] mcp-ui/sizeChanged ${p.width}x${p.height}`);
             this.onSizeChanged?.(p);
         });
     }
 
+    get appCapabilities(): AppCapabilities | undefined {
+        return this.ui.getPeerSettings();
+    }
+
     notifyToolResult(toolName: string, text: string) {
-        return this.server.sendCustomNotification('mcp-ui/toolResult', {
+        return this.ui.sendNotification('mcp-ui/toolResult', {
             toolName,
             content: [{ type: 'text', text }]
         });
     }
 
     notifyHostContextChanged(patch: z.infer<typeof HostContextChangedParams>) {
-        return this.server.sendCustomNotification('mcp-ui/hostContextChanged', patch);
+        return this.ui.sendNotification('mcp-ui/hostContextChanged', patch);
     }
 
     requestTeardown(reason: string) {
-        return this.server.sendCustomRequest('mcp-ui/resourceTeardown', { reason }, z.object({}));
+        return this.ui.sendRequest('mcp-ui/resourceTeardown', { reason }, z.object({}));
     }
 }
 
@@ -169,7 +174,7 @@ class Host {
 
 async function main() {
     const host = new Host();
-    const app = new App({ name: 'demo-app', version: '1.0.0' });
+    const app = new App({ name: 'demo-app', version: '1.0.0' }, { availableDisplayModes: ['inline', 'fullscreen'] });
 
     app.addEventListener('toolresult', p => console.log(`[app] toolresult: ${p.toolName} -> "${p.content[0]?.text}"`));
     app.addEventListener('hostcontextchanged', p => console.log(`[app] hostcontextchanged: ${JSON.stringify(p)}`));
@@ -180,6 +185,9 @@ async function main() {
     await host.server.connect(serverTransport);
     await app.connect(clientTransport);
 
+    // Capability negotiation via MCP initialize — both sides see each other's extensions[EXT_ID]
+    console.log(`[app] hostCapabilities: ${JSON.stringify(app.hostCapabilities)}`);
+    console.log(`[host] appCapabilities: ${JSON.stringify(host.appCapabilities)}`);
     console.log(`[app] hostContext after init: ${JSON.stringify(app.getHostContext())}`);
 
     // App -> Host: custom request

packages/client/src/client/client.ts

@@ -1,5 +1,6 @@
 import { DefaultJsonSchemaValidator } from '@modelcontextprotocol/client/_shims';
 import type {
+    AnySchema,
     BaseContext,
     CallToolRequest,
     ClientCapabilities,
@@ -8,8 +9,10 @@ import type {
     ClientRequest,
     ClientResult,
     CompleteRequest,
+    ExtensionOptions,
     GetPromptRequest,
     Implementation,
+    JSONObject,
     JsonSchemaType,
     JsonSchemaValidator,
     jsonSchemaValidator,
@@ -28,6 +31,7 @@ import type {
     RequestOptions,
     RequestTypeMap,
     ResultTypeMap,
+    SchemaOutput,
     ServerCapabilities,
     SubscribeRequest,
     TaskManagerOptions,
@@ -47,6 +51,7 @@ import {
     ElicitRequestSchema,
     ElicitResultSchema,
     EmptyResultSchema,
+    ExtensionHandle,
     extractTaskManagerOptions,
     GetPromptResultSchema,
     InitializeResultSchema,
@@ -307,6 +312,40 @@ export class Client extends Protocol<ClientContext> {
         this._capabilities = mergeCapabilities(this._capabilities, capabilities);
     }
 
+    /**
+     * Declares an SEP-2133 extension and returns a scoped {@linkcode ExtensionHandle} for
+     * registering and sending its custom JSON-RPC methods.
+     *
+     * Merges `settings` into `capabilities.extensions[id]`, which is advertised to the server
+     * during `initialize`. Must be called before {@linkcode connect}. After connecting,
+     * {@linkcode ExtensionHandle.getPeerSettings | handle.getPeerSettings()} returns the server's
+     * `capabilities.extensions[id]` blob (validated against `peerSchema` if provided).
+     */
+    public extension<L extends JSONObject>(id: string, settings: L): ExtensionHandle<L, JSONObject, ClientContext>;
+    public extension<L extends JSONObject, P extends AnySchema>(
+        id: string,
+        settings: L,
+        opts: ExtensionOptions<P>
+    ): ExtensionHandle<L, SchemaOutput<P>, ClientContext>;
+    public extension<L extends JSONObject, P extends AnySchema>(
+        id: string,
+        settings: L,
+        opts?: ExtensionOptions<P>
+    ): ExtensionHandle<L, SchemaOutput<P> | JSONObject, ClientContext> {
+        if (this.transport) {
+            throw new SdkError(SdkErrorCode.AlreadyConnected, 'Cannot register extension after connecting to transport');
+        }
+        this._capabilities.extensions = { ...this._capabilities.extensions, [id]: settings };
+        return new ExtensionHandle(
+            this,
+            id,
+            settings,
+            () => this._serverCapabilities?.extensions?.[id],
+            this._enforceStrictCapabilities,
+            opts?.peerSchema
+        );
+    }
+
     /**
      * Registers a handler for server-initiated requests (sampling, elicitation, roots).
      * The client must declare the corresponding capability for the handler to be accepted.

packages/core/src/exports/public/index.ts

@@ -35,6 +35,10 @@ export type {
 // Auth utilities
 export { checkResourceAllowed, resourceUrlFromServerUrl } from '../../shared/authUtils.js';
 
+// Extension registrar (SEP-2133 capability-aware custom methods)
+export type { ExtensionOptions } from '../../shared/extensionHandle.js';
+export { ExtensionHandle } from '../../shared/extensionHandle.js';
+
 // Metadata utilities
 export { getDisplayName } from '../../shared/metadataUtils.js';
 

packages/core/src/index.ts

@@ -2,6 +2,7 @@ export * from './auth/errors.js';
 export * from './errors/sdkErrors.js';
 export * from './shared/auth.js';
 export * from './shared/authUtils.js';
+export * from './shared/extensionHandle.js';
 export * from './shared/metadataUtils.js';
 export * from './shared/protocol.js';
 export * from './shared/responseMessage.js';