|
| 1 | +--- |
| 2 | +shape: how-to |
| 3 | +--- |
| 4 | + |
| 5 | +# Server extensions |
| 6 | + |
| 7 | +::: warning Experimental |
| 8 | +The `extensions` option, the `ServerExtension` and `ClientExtension` shapes, `use` and `acceptResultType` are experimental and may change in a minor release. |
| 9 | +::: |
| 10 | + |
| 11 | +A **server extension** packages protocol behaviour outside the core specification, such as the `io.modelcontextprotocol/tasks` or `io.modelcontextprotocol/skills` extension or a vendor feature, as one object you pass to the server. The SDK advertises it and installs it, and gives it hooks at two levels: the protocol, where it adds methods and middleware, and the high-level `McpServer`, where it registers resources and tools. What the extension does behind those hooks is its own business. |
| 12 | + |
| 13 | +## Write an extension |
| 14 | + |
| 15 | +An extension is an `id` plus one or both of two hooks: |
| 16 | + |
| 17 | +- `install(server)` receives the low-level `Server`. Use it for custom methods (`setRequestHandler`), middleware on spec methods (`use`), notification handlers and capability settings (`registerCapabilities`). It runs on both `Server` and `McpServer`. |
| 18 | +- `attach(mcp)` receives the `McpServer`. Use it for anything registered through the high-level API, such as `registerResource` with a `ResourceTemplate`, or `registerTool`. It runs only through `McpServer`. |
| 19 | + |
| 20 | +This extension works at the protocol level only: |
| 21 | + |
| 22 | +```ts |
| 23 | +import type { ServerExtension } from '@modelcontextprotocol/server'; |
| 24 | +import { MissingRequiredClientCapabilityError, CLIENT_CAPABILITIES_META_KEY } from '@modelcontextprotocol/server'; |
| 25 | +import * as z from 'zod/v4'; |
| 26 | + |
| 27 | +const GATE = 'com.example/gate'; |
| 28 | + |
| 29 | +export const gate: ServerExtension = { |
| 30 | + id: GATE, |
| 31 | + install(server) { |
| 32 | + // Settings for the advertised capability, if the extension has any. |
| 33 | + server.registerCapabilities({ extensions: { [GATE]: { exampleData: true } } }); |
| 34 | + |
| 35 | + // A custom method, exactly as in Custom methods. |
| 36 | + server.setRequestHandler('gate/status', { params: z.looseObject({}) }, () => ({ armed: true })); |
| 37 | + |
| 38 | + // Middleware on a spec method: runs around the registered handler, |
| 39 | + // may answer, transform, or refuse. |
| 40 | + server.use('tools/call', (request, ctx, next) => { |
| 41 | + const declared = ctx.mcpReq.envelope?.[CLIENT_CAPABILITIES_META_KEY]?.extensions ?? {}; |
| 42 | + if (!(GATE in declared)) { |
| 43 | + throw new MissingRequiredClientCapabilityError({ requiredCapabilities: { extensions: { [GATE]: {} } } }, 'declare the gate'); |
| 44 | + } |
| 45 | + return next(request, ctx); |
| 46 | + }); |
| 47 | + } |
| 48 | +}; |
| 49 | +``` |
| 50 | + |
| 51 | +An extension that serves resources attaches instead. The Skills extension is one: it has an `id` and an `attach(mcp)`, so it is a `ServerExtension` as it stands. |
| 52 | + |
| 53 | +```ts |
| 54 | +import { McpServer } from '@modelcontextprotocol/server'; |
| 55 | +import { loadSkills } from '@modelcontextprotocol/server/ext/skills/node'; |
| 56 | + |
| 57 | +const skills = await loadSkills('./skills'); |
| 58 | +const server = new McpServer({ name: 'skills-server', version: '1.0.0' }, { extensions: [skills] }); |
| 59 | +``` |
| 60 | + |
| 61 | +Passing it in `extensions` is the same as calling `skills.attach(server)` before connecting. |
| 62 | + |
| 63 | +## Install it |
| 64 | + |
| 65 | +Pass extensions at construction: |
| 66 | + |
| 67 | +```ts |
| 68 | +const server = new McpServer({ name: 'gated', version: '1.0.0' }, { extensions: [gate, skills] }); |
| 69 | +``` |
| 70 | + |
| 71 | +The server then does three things, in this order: |
| 72 | + |
| 73 | +1. Advertises each extension under `capabilities.extensions[id]` as `{}`. Legacy connections see it in the `initialize` result, and 2026-07-28 connections see it in `server/discover`. Settings an extension registers itself replace the `{}`. |
| 74 | +2. Runs every `install`, in array order, after the built-in handlers exist. |
| 75 | +3. Runs every `attach`, in array order. |
| 76 | + |
| 77 | +Construction fails before anything is installed if two extensions share an `id`, or if an extension has neither hook. A hook that throws fails the constructor, so a server with a partly installed extension never exists. |
| 78 | + |
| 79 | +The low-level `Server` takes the same `extensions` option and runs only `install`. It refuses an extension that has `attach`, because that extension needs `McpServer`. |
| 80 | + |
| 81 | +## Client extensions |
| 82 | + |
| 83 | +The client half has one level: `ClientExtension` is `{ id, install(client) }`, passed in `ClientOptions.extensions`. The client advertises it under its own `capabilities.extensions[id]`. On a legacy connection that is the `initialize` request, and on a 2026-07-28 connection it is every request's `_meta` client-capabilities envelope, which is where a server extension reads it. `install` receives the `Client` to register handlers for server-to-client requests and notifications, or to wrap the ones the SDK installs with middleware. A duplicate `id` fails construction here too. |
| 84 | + |
| 85 | +```ts |
| 86 | +import type { ClientExtension } from '@modelcontextprotocol/client'; |
| 87 | + |
| 88 | +const gateClient: ClientExtension = { |
| 89 | + id: GATE, |
| 90 | + install(client) { |
| 91 | + client.setRequestHandler('gate/ping', { params: z.looseObject({}) }, () => ({ pong: true })); |
| 92 | + // Results of tools/call may carry the extension's own kind; the |
| 93 | + // explicit-schema request() path then hands them to the caller's |
| 94 | + // schema as-is instead of rejecting the unknown resultType. |
| 95 | + client.acceptResultType('tools/call', 'gate'); |
| 96 | + } |
| 97 | +}; |
| 98 | + |
| 99 | +const client = new Client({ name: 'gated-client', version: '1.0.0' }, { extensions: [gateClient] }); |
| 100 | +``` |
| 101 | + |
| 102 | +## How middleware composes |
| 103 | + |
| 104 | +`setRequestHandler` is the route handler. `use(method, middleware)` is the middleware around it, in the Koa style: `await next(request, ctx)` yields the result, and the middleware returns what goes on the wire. It wraps whatever handler serves `method` at dispatch time, including a handler another extension registered. That matters for `tools/call`, which `McpServer` registers on the first tool registration: middleware installed at construction still applies. With no underlying handler, `next` throws `MethodNotFound`. |
| 105 | + |
| 106 | +Several middleware nest in registration order, the first installed outermost. The returned function removes the middleware. Method names are exact, and there is no wildcard. |
| 107 | + |
| 108 | +An extension wraps the methods it doesn't own with `use`, and never registers them again. Something every peer must know about the extension belongs in its advertised capability (`registerCapabilities`), not in per-request `_meta`. Where a result does carry extension `_meta`, the middleware adds its own namespaced key, and the encoder still stamps the SDK's reserved keys and `resultType` on top. |
| 109 | + |
| 110 | +A thrown `ProtocolError` becomes the JSON-RPC error response. Inside a tool handler, `McpServer` converts most throws into an `isError` tool result. The exceptions are the protocol-level errors the client must see as errors: `UrlElicitationRequiredError` and `MissingRequiredClientCapabilityError` (`-32021`). |
| 111 | + |
| 112 | +## Recap |
| 113 | + |
| 114 | +- `ServerExtension` is `{ id, install?(server), attach?(mcp) }`, passed in `extensions`. `install` gets the low-level `Server` and `attach` gets the `McpServer`. |
| 115 | +- Every `install` runs before every `attach`, each in array order. Only `McpServer` runs `attach`. |
| 116 | +- Duplicate ids, and extensions with no hook, fail construction before anything is installed. |
| 117 | +- `ClientExtension` is `{ id, install(client) }` on `ClientOptions.extensions`. |
| 118 | +- Middleware composes at dispatch time, in registration order, and applies to handlers registered later, including other extensions' handlers. |
| 119 | +- `acceptResultType(method, resultType)` lets a client extension receive a result kind outside `complete` / `input_required` through the explicit-schema `request()` path. |
| 120 | +- The SDK owns the hooks and the capability advertisement, not the extension's state or execution. |
0 commit comments