docs: add client.md/server.md sections and @example blocks for extension() and custom methods

Author: felixweinberger

docs/client.md

@@ -29,6 +29,7 @@ import {
     StdioClientTransport,
     StreamableHTTPClientTransport
 } from '@modelcontextprotocol/client';
+import * as z from 'zod/v4';
 ```
 
 ## Connecting to a server
@@ -596,6 +597,66 @@ console.log(result);
 
 For an end-to-end example of server-initiated SSE disconnection and automatic client reconnection with event replay, see [`ssePollingClient.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/ssePollingClient.ts).
 
+## Protocol extensions
+
+[SEP-2133](https://modelcontextprotocol.io/seps/2133) defines a `capabilities.extensions` field that lets clients and servers advertise support for protocol extensions outside the core MCP spec. This SDK provides two layers for implementing the JSON-RPC methods such an extension defines: {@linkcode @modelcontextprotocol/client!client/client.Client#extension | Client.extension()} for capability-aware extensions, and the lower-level {@linkcode @modelcontextprotocol/client!client/client.Client#setCustomRequestHandler | setCustomRequestHandler} / {@linkcode @modelcontextprotocol/client!client/client.Client#sendCustomRequest | sendCustomRequest} family for ungated one-off methods.
+
+### Declaring an extension
+
+Call {@linkcode @modelcontextprotocol/client!client/client.Client#extension | client.extension(id, settings)} before connecting. This merges `settings` into `capabilities.extensions[id]` (sent to the server during `initialize`) and returns an {@linkcode @modelcontextprotocol/client!index.ExtensionHandle | ExtensionHandle} for registering handlers and sending requests:
+
+```ts source="../examples/client/src/clientGuide.examples.ts#extension_declare"
+const client = new Client({ name: 'ui-view', version: '1.0.0' });
+
+// Declare the extension. `settings` is advertised in capabilities.extensions[id] during initialize.
+const ui = client.extension(
+    'io.modelcontextprotocol/ui',
+    { availableModes: ['inline', 'fullscreen'] },
+    { peerSchema: z.object({ openLinks: z.boolean().optional() }) }
+);
+
+// Handle incoming custom notifications from the server.
+ui.setNotificationHandler('ui/host-context-changed', z.object({ theme: z.enum(['light', 'dark']) }), params => {
+    document.body.dataset.theme = params.theme;
+});
+```
+
+The handle is the only way to reach `ui.setNotificationHandler(...)`, so a handler registered through it is structurally guaranteed to belong to a declared extension.
+
+After connecting, {@linkcode @modelcontextprotocol/client!index.ExtensionHandle#getPeerSettings | handle.getPeerSettings()} returns what the server advertised for the same extension ID, and {@linkcode @modelcontextprotocol/client!index.ExtensionHandle#sendRequest | handle.sendRequest()} sends a custom request gated on that:
+
+```ts source="../examples/client/src/clientGuide.examples.ts#extension_send"
+await client.connect(transport);
+
+// After connect, read the server's advertised settings for this extension.
+if (ui.getPeerSettings()?.openLinks) {
+    const result = await ui.sendRequest('ui/open-link', { url: 'https://example.com' }, z.object({ opened: z.boolean() }));
+    console.log(result.opened);
+}
+```
+
+When `enforceStrictCapabilities` is enabled, `sendRequest()` and `sendNotification()` throw if the server did not advertise the extension. Under the default (lax) mode they send regardless, and `getPeerSettings()` returns `undefined`.
+
+### Ungated custom methods
+
+For a one-off vendor method that does not warrant an SEP-2133 capability entry, use the flat custom-method API directly on the client. This skips capability negotiation entirely:
+
+```ts source="../examples/client/src/clientGuide.examples.ts#customMethod_ungated"
+// For one-off vendor methods that do not warrant an SEP-2133 capability entry,
+// use the flat custom-method API directly.
+const result = await client.sendCustomRequest('acme/search', { query: 'widgets' }, z.object({ hits: z.array(z.string()) }));
+console.log(result.hits);
+```
+
+Standard MCP method names are rejected with a clear error — use {@linkcode @modelcontextprotocol/client!client/client.Client#callTool | callTool()} and friends for those.
+
+### When to use which
+
+| Use | When |
+| --- | --- |
+| `client.extension(id, ...)` | You implement an SEP-2133 extension with a published ID, want it advertised in `capabilities`, and want sends gated on the peer supporting it. |
+| `sendCustomRequest` etc. | You need a single vendor-specific method without capability negotiation, or are prototyping before defining an extension. |
+
 ## Tasks (experimental)
 
 > [!WARNING]

docs/server.md

@@ -22,7 +22,7 @@ import { randomUUID } from 'node:crypto';
 import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { CallToolResult, ResourceLink } from '@modelcontextprotocol/server';
-import { completable, McpServer, ResourceTemplate, StdioServerTransport } from '@modelcontextprotocol/server';
+import { completable, McpServer, ResourceTemplate, Server, StdioServerTransport } from '@modelcontextprotocol/server';
 import * as z from 'zod/v4';
 ```
 
@@ -494,6 +494,74 @@ server.registerTool(
 );
 ```
 
+## Protocol extensions
+
+[SEP-2133](https://modelcontextprotocol.io/seps/2133) defines a `capabilities.extensions` field that lets servers and clients advertise support for protocol extensions outside the core MCP spec — for example, [MCP Apps](https://modelcontextprotocol.io/seps/1865) (`io.modelcontextprotocol/ui`). This SDK provides two layers for implementing the JSON-RPC methods such an extension defines: {@linkcode @modelcontextprotocol/server!server/server.Server#extension | Server.extension()} for capability-aware extensions, and the lower-level {@linkcode @modelcontextprotocol/server!server/server.Server#setCustomRequestHandler | setCustomRequestHandler} family for ungated one-off methods.
+
+### Declaring an extension
+
+Call {@linkcode @modelcontextprotocol/server!server/server.Server#extension | server.extension(id, settings)} before connecting. This merges `settings` into `capabilities.extensions[id]` (advertised to the client during `initialize`) and returns an {@linkcode @modelcontextprotocol/server!index.ExtensionHandle | ExtensionHandle} for registering handlers and sending requests:
+
+```ts source="../examples/server/src/serverGuide.examples.ts#extension_declare"
+const server = new Server({ name: 'host', version: '1.0.0' }, { capabilities: {} });
+
+// Declare the extension. `settings` is advertised in capabilities.extensions[id] during initialize.
+const ui = server.extension(
+    'io.modelcontextprotocol/ui',
+    { openLinks: true, downloadFile: true },
+    { peerSchema: z.object({ availableModes: z.array(z.string()) }) }
+);
+
+// Register handlers for the extension's custom methods. The handle is proof of declaration —
+// you cannot reach this point without the capability having been merged in above.
+ui.setRequestHandler('ui/open-link', z.object({ url: z.string() }), async params => {
+    return { opened: params.url.startsWith('https://') };
+});
+
+ui.setNotificationHandler('ui/size-changed', z.object({ width: z.number(), height: z.number() }), params => {
+    console.log(`view resized to ${params.width}x${params.height}`);
+});
+```
+
+The handle is the only way to reach `ui.setRequestHandler(...)`, so a handler registered through it is structurally guaranteed to belong to a declared extension — you cannot forget the capability declaration.
+
+After connecting, {@linkcode @modelcontextprotocol/server!index.ExtensionHandle#getPeerSettings | handle.getPeerSettings()} returns what the client advertised for the same extension ID. Pass a `peerSchema` to type and validate that blob:
+
+```ts source="../examples/server/src/serverGuide.examples.ts#extension_peerSettings"
+await server.connect(transport);
+
+// After connect, read what the client advertised for this extension.
+const clientUi = ui.getPeerSettings(); // { availableModes: string[] } | undefined
+if (clientUi?.availableModes.includes('fullscreen')) {
+    await ui.sendNotification('ui/mode-available', { mode: 'fullscreen' });
+}
+```
+
+When `enforceStrictCapabilities` is enabled, {@linkcode @modelcontextprotocol/server!index.ExtensionHandle#sendRequest | handle.sendRequest()} and {@linkcode @modelcontextprotocol/server!index.ExtensionHandle#sendNotification | sendNotification()} throw if the client did not advertise the extension. Under the default (lax) mode they send regardless, and `getPeerSettings()` returns `undefined`.
+
+### Ungated custom methods
+
+For a one-off vendor method that does not warrant an SEP-2133 capability entry, use the flat custom-method API directly on the server. This skips capability negotiation entirely:
+
+```ts source="../examples/server/src/serverGuide.examples.ts#customMethod_ungated"
+// For one-off vendor methods that do not warrant an SEP-2133 capability entry,
+// use the flat custom-method API directly.
+server.setCustomRequestHandler('acme/search', z.object({ query: z.string() }), async params => {
+    return { hits: [`result for ${params.query}`] };
+});
+```
+
+The companion {@linkcode @modelcontextprotocol/server!server/server.Server#sendCustomRequest | sendCustomRequest}, {@linkcode @modelcontextprotocol/server!server/server.Server#setCustomNotificationHandler | setCustomNotificationHandler}, and {@linkcode @modelcontextprotocol/server!server/server.Server#sendCustomNotification | sendCustomNotification} cover the other directions. Standard MCP method names are rejected with a clear error — use {@linkcode @modelcontextprotocol/server!server/server.Server#setRequestHandler | setRequestHandler} for those.
+
+### When to use which
+
+| Use | When |
+| --- | --- |
+| `server.extension(id, ...)` | You implement an SEP-2133 extension with a published ID, want it advertised in `capabilities`, and want sends gated on the peer supporting it. |
+| `setCustomRequestHandler` etc. | You need a single vendor-specific method without capability negotiation, or are prototyping before defining an extension. |
+
+For a full runnable example, see [`customMethodExample.ts`](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/customMethodExample.ts).
+
 ## Tasks (experimental)
 
 > [!WARNING]

examples/client/src/clientGuide.examples.ts

@@ -24,6 +24,7 @@ import {
     StdioClientTransport,
     StreamableHTTPClientTransport
 } from '@modelcontextprotocol/client';
+import * as z from 'zod/v4';
 //#endregion imports
 
 // ---------------------------------------------------------------------------
@@ -544,6 +545,54 @@ async function resumptionToken_basic(client: Client) {
     //#endregion resumptionToken_basic
 }
 
+// ---------------------------------------------------------------------------
+// Protocol extensions
+// ---------------------------------------------------------------------------
+
+/** Example: declare an SEP-2133 extension on a Client and wire handlers + sends. */
+function extension_declare() {
+    //#region extension_declare
+    const client = new Client({ name: 'ui-view', version: '1.0.0' });
+
+    // Declare the extension. `settings` is advertised in capabilities.extensions[id] during initialize.
+    const ui = client.extension(
+        'io.modelcontextprotocol/ui',
+        { availableModes: ['inline', 'fullscreen'] },
+        { peerSchema: z.object({ openLinks: z.boolean().optional() }) }
+    );
+
+    // Handle incoming custom notifications from the server.
+    ui.setNotificationHandler('ui/host-context-changed', z.object({ theme: z.enum(['light', 'dark']) }), params => {
+        document.body.dataset.theme = params.theme;
+    });
+    //#endregion extension_declare
+    return { client, ui };
+}
+
+/** Example: send a custom request through the handle and read peer settings. */
+async function extension_send() {
+    const { client, ui } = extension_declare();
+    //#region extension_send
+    await client.connect(transport);
+
+    // After connect, read the server's advertised settings for this extension.
+    if (ui.getPeerSettings()?.openLinks) {
+        const result = await ui.sendRequest('ui/open-link', { url: 'https://example.com' }, z.object({ opened: z.boolean() }));
+        console.log(result.opened);
+    }
+    //#endregion extension_send
+}
+
+/** Example: ungated custom method (no capability negotiation). */
+async function customMethod_ungated(client: Client) {
+    //#region customMethod_ungated
+    // For one-off vendor methods that do not warrant an SEP-2133 capability entry,
+    // use the flat custom-method API directly.
+    const result = await client.sendCustomRequest('acme/search', { query: 'widgets' }, z.object({ hits: z.array(z.string()) }));
+    console.log(result.hits);
+    //#endregion customMethod_ungated
+}
+
 // Suppress unused-function warnings (functions exist solely for type-checking)
 void connect_streamableHttp;
 void connect_stdio;
@@ -573,3 +622,9 @@ void errorHandling_lifecycle;
 void errorHandling_timeout;
 void middleware_basic;
 void resumptionToken_basic;
+void extension_declare;
+void extension_send;
+void customMethod_ungated;
+
+declare const transport: import('@modelcontextprotocol/client').Transport;
+declare const document: { body: { dataset: Record<string, string> } };

examples/server/src/serverGuide.examples.ts

@@ -13,7 +13,7 @@ import { randomUUID } from 'node:crypto';
 import { createMcpExpressApp } from '@modelcontextprotocol/express';
 import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
 import type { CallToolResult, ResourceLink } from '@modelcontextprotocol/server';
-import { completable, McpServer, ResourceTemplate, StdioServerTransport } from '@modelcontextprotocol/server';
+import { completable, McpServer, ResourceTemplate, Server, StdioServerTransport } from '@modelcontextprotocol/server';
 import * as z from 'zod/v4';
 //#endregion imports
 
@@ -534,6 +534,62 @@ function dnsRebinding_allowedHosts() {
     return app;
 }
 
+// ---------------------------------------------------------------------------
+// Protocol extensions
+// ---------------------------------------------------------------------------
+
+/** Example: declare an SEP-2133 extension on a low-level Server and wire handlers. */
+function extension_declare() {
+    //#region extension_declare
+    const server = new Server({ name: 'host', version: '1.0.0' }, { capabilities: {} });
+
+    // Declare the extension. `settings` is advertised in capabilities.extensions[id] during initialize.
+    const ui = server.extension(
+        'io.modelcontextprotocol/ui',
+        { openLinks: true, downloadFile: true },
+        { peerSchema: z.object({ availableModes: z.array(z.string()) }) }
+    );
+
+    // Register handlers for the extension's custom methods. The handle is proof of declaration —
+    // you cannot reach this point without the capability having been merged in above.
+    ui.setRequestHandler('ui/open-link', z.object({ url: z.string() }), async params => {
+        return { opened: params.url.startsWith('https://') };
+    });
+
+    ui.setNotificationHandler('ui/size-changed', z.object({ width: z.number(), height: z.number() }), params => {
+        console.log(`view resized to ${params.width}x${params.height}`);
+    });
+    //#endregion extension_declare
+    return { server, ui };
+}
+
+/** Example: read the connected client's extension settings. */
+async function extension_peerSettings() {
+    const { server, ui } = extension_declare();
+    //#region extension_peerSettings
+    await server.connect(transport);
+
+    // After connect, read what the client advertised for this extension.
+    const clientUi = ui.getPeerSettings(); // { availableModes: string[] } | undefined
+    if (clientUi?.availableModes.includes('fullscreen')) {
+        await ui.sendNotification('ui/mode-available', { mode: 'fullscreen' });
+    }
+    //#endregion extension_peerSettings
+}
+
+/** Example: ungated custom method (no capability negotiation). */
+function customMethod_ungated() {
+    const server = new Server({ name: 'host', version: '1.0.0' }, { capabilities: {} });
+    //#region customMethod_ungated
+    // For one-off vendor methods that do not warrant an SEP-2133 capability entry,
+    // use the flat custom-method API directly.
+    server.setCustomRequestHandler('acme/search', z.object({ query: z.string() }), async params => {
+        return { hits: [`result for ${params.query}`] };
+    });
+    //#endregion customMethod_ungated
+    return server;
+}
+
 // Suppress unused-function warnings (functions exist solely for type-checking)
 void instructions_basic;
 void registerTool_basic;
@@ -557,3 +613,8 @@ void shutdown_statefulHttp;
 void shutdown_stdio;
 void dnsRebinding_basic;
 void dnsRebinding_allowedHosts;
+void extension_declare;
+void extension_peerSettings;
+void customMethod_ungated;
+
+declare const transport: import('@modelcontextprotocol/server').Transport;

packages/client/src/client/client.examples.ts

@@ -8,6 +8,7 @@
  */
 
 import type { Prompt, Resource, Tool } from '@modelcontextprotocol/core';
+import * as z from 'zod/v4';
 
 import { Client } from './client.js';
 import { SSEClientTransport } from './sse.js';
@@ -192,3 +193,27 @@ async function Client_listResources_pagination(client: Client) {
     );
     //#endregion Client_listResources_pagination
 }
+
+/**
+ * Example: declare an SEP-2133 extension and use the returned handle.
+ */
+function Client_extension_basic() {
+    //#region Client_extension_basic
+    const client = new Client({ name: 'ui-view', version: '1.0.0' });
+
+    const ui = client.extension(
+        'io.modelcontextprotocol/ui',
+        { availableModes: ['inline', 'fullscreen'] },
+        { peerSchema: z.object({ openLinks: z.boolean().optional() }) }
+    );
+
+    ui.setNotificationHandler('ui/tool-result', z.object({ content: z.array(z.unknown()) }), params => {
+        console.log('tool result:', params.content);
+    });
+
+    // After connect: ui.getPeerSettings() returns the server's extensions['io.modelcontextprotocol/ui']
+    //#endregion Client_extension_basic
+    return { client, ui };
+}
+
+void Client_extension_basic;

packages/client/src/client/client.ts

@@ -324,6 +324,23 @@ export class Client extends Protocol<ClientContext> {
      * Note: a later {@linkcode registerCapabilities} call that includes `extensions[id]` will
      * overwrite the wire value declared here; the returned handle's `settings` reflects what
      * was passed to this call, not subsequent overwrites.
+     *
+     * @example
+     * ```ts source="./client.examples.ts#Client_extension_basic"
+     * const client = new Client({ name: 'ui-view', version: '1.0.0' });
+     *
+     * const ui = client.extension(
+     *     'io.modelcontextprotocol/ui',
+     *     { availableModes: ['inline', 'fullscreen'] },
+     *     { peerSchema: z.object({ openLinks: z.boolean().optional() }) }
+     * );
+     *
+     * ui.setNotificationHandler('ui/tool-result', z.object({ content: z.array(z.unknown()) }), params => {
+     *     console.log('tool result:', params.content);
+     * });
+     *
+     * // After connect: ui.getPeerSettings() returns the server's extensions['io.modelcontextprotocol/ui']
+     * ```
      */
     public extension<L extends JSONObject>(id: string, settings: L): ExtensionHandle<L, JSONObject, ClientContext>;
     public extension<L extends JSONObject, P extends AnySchema>(