This is the documentation for v2 — looking for the v1 documentation?
Skip to content

MCP TypeScript SDK (V2) / @modelcontextprotocol/server / server/extension

server/extension ​

Interfaces ​

ServerExtension ​

Defined in: packages/server/src/server/extension.ts:38

Experimental

A server extension: protocol behaviour outside the core specification, such as the io.modelcontextprotocol/tasks extension or a vendor feature, passed to the server at construction.

ts
const server = new McpServer(info, { extensions: [tasks, skills] });

What is both required and declarative sits on the object: the id. Everything else happens in setup, which runs once while the server is constructed: optional declarations first (ctx.capability, ctx.require), then custom request handlers, middleware on spec methods, and anything registered on the McpServer itself, such as resources and tools.

Experimental: may change in a minor release while the extensions SEPs settle.

Properties ​

id ​

readonly id: string

Defined in: packages/server/src/server/extension.ts:44

Experimental

The extension identifier, prefix-qualified (io.modelcontextprotocol/tasks, com.example/feature-flags). Advertised as the key under capabilities.extensions, and unique per server.

Methods ​

setup() ​

setup(ctx): void | Promise<void>

Defined in: packages/server/src/server/extension.ts:50

Experimental

Adds the extension to the server. Called once, at construction, in extensions order. It may be async: the setups after it wait for it, and connect waits for all of them and rejects if one fails.

Parameters ​
ctx ​

ServerExtensionContext

Returns ​

void | Promise<void>


ServerExtensionContext ​

Defined in: packages/server/src/server/extension.ts:60

Experimental

What a ServerExtension's setup receives.

Experimental: may change in a minor release while the extensions SEPs settle.

Properties ​

mcp ​

readonly mcp: McpServer

Defined in: packages/server/src/server/extension.ts:62

Experimental

The server the extension is set up on: registerTool, registerResource, ResourceTemplate.

Methods ​

capability() ​

capability(settings): void

Defined in: packages/server/src/server/extension.ts:68

Experimental

Sets what the server advertises under capabilities.extensions[id]. Without a call, the server advertises {}. The entry belongs to the extension: setting it anywhere else throws.

Parameters ​
settings ​

JSONObject

Returns ​

void

require() ​

require(extensionId): void

Defined in: packages/server/src/server/extension.ts:76

Experimental

Declares that this extension needs another extension, by id. Throws, naming both, when the server doesn't install it, which fails the constructor, or connect from or after an async setup. The full list is known before any setup runs, so an extension listed after this one counts. For behaviour that is merely optional, check in code instead and carry on without it.

Parameters ​
extensionId ​

`${string}/${string}`

Returns ​

void

setRequestHandler() ​

setRequestHandler<P, R>(name, schemas, handler): void

Defined in: packages/server/src/server/extension.ts:92

Experimental

Registers the handler for a custom request method, like Server.setRequestHandler with schemas, but checked: throws when name is a core request (wrap those with use instead) or notification, or when a handler already serves it, such as another extension's.

Type Parameters ​
P ​

P extends StandardSchemaV1<unknown, unknown>

R ​

R extends StandardSchemaV1<unknown, unknown> | undefined = undefined

Parameters ​
name ​

string

schemas ​
params ​

P

result? ​

R

handler ​

(params, ctx) => InferHandlerResult<R> | Promise<InferHandlerResult<R>>

Returns ​

void

use() ​

use(method, middleware): void

Defined in: packages/server/src/server/extension.ts:85

Experimental

Middleware around whatever handler serves method, a request this server receives, including a core method or another extension's: it may answer, transform or refuse. Throws a TypeError for a method it could never wrap. Runs outside middleware the application adds with mcp.server.use, and inside middleware from extensions earlier in extensions. See Protocol.use for how middleware composes.

Parameters ​
method ​

RequestMethod | string & object

middleware ​

RequestMiddleware<ServerContext>

Returns ​

void

Functions ​

installServerExtensions() ​

installServerExtensions(mcp, extensions): void

Defined in: packages/server/src/server/extension.ts:100

Package-internal: sets extensions up for the constructor (see installExtensions).

Parameters ​

mcp ​

McpServer

extensions ​

readonly ServerExtension[]

Returns ​

void