Class MCPServer<TUser, TEnv>

MCP server with declarative tool/resource/prompt registration, served statelessly over a composed fetch handler.

Registrations are stored in a registry; a fresh SDK McpServer is built from it for every HTTP request (the stateless 2026-07-28 model), so definition-time work must stay cheap — put pools and caches at module scope, not inside callbacks' setup.

Example

const server = new MCPServer({ name: "my-server", version: "1.0.0" });
server.tool(
  { name: "add", inputSchema: z.object({ a: z.number(), b: z.number() }) },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);
await server.listen(3000);

Type Parameters

TUser = never
TEnv extends Env = Env

Index

Constructors

constructor

new MCPServer<TUser = never, TEnv extends Env = Env>(
config: ServerConfig<TUser>,
): MCPServer<TUser, TEnv>
Create a server. config.name and config.version identify the server to clients during initialization. config.basePath (default "/mcp") is both the MCP route and the path of the OAuth protected-resource identity, so any explicit OAuth resource URL must use that exact path. Nothing binds or listens until MCPServer.listen or the first request reaches MCPServer.fetch.
Type Parameters
- TUser = never
- TEnv extends Env = Env
Parameters
- config: ServerConfig<TUser>
Returns MCPServer<TUser, TEnv>
- Defined in server.ts:507

Properties

`Readonly`all

all: HandlerInterface<TEnv, "all", BlankSchema, "/", "/">

`Readonly`app

app: Hono<TEnv>

Hono application that owns HTTP middleware and routes.

`Readonly`delete

delete: HandlerInterface<TEnv, "delete", BlankSchema, "/", "/">

`Readonly`fetch

fetch: (
    ...args: [
        request: Request,
        env?: {}
        | TEnv["Bindings"],
        executionCtx?: ExecutionContext,
    ],
) => Promise<Response>

Canonical Web-standard handler for edge runtimes and framework mounting.

Example

export default server;
// or: export const POST = server.fetch;

`Readonly`get

get: HandlerInterface<TEnv, "get", BlankSchema, "/", "/">

`Readonly`patch

patch: HandlerInterface<TEnv, "patch", BlankSchema, "/", "/">

`Readonly`post

post: HandlerInterface<TEnv, "post", BlankSchema, "/", "/">

`Readonly`put

put: HandlerInterface<TEnv, "put", BlankSchema, "/", "/">

Accessors

basePath

get basePath(): string
The URL path prefix the MCP endpoint is mounted at.

Reflects config.basePath (default "/mcp"). Exposed so tooling that imports the entry module — mcp-use dev's startup log, for example — can build endpoint and development-tool URLs without assuming the default.

Returns string
- Defined in server.ts:548

branding

get branding(): ServerBranding
Immutable normalized branding shared by MCP identity and browser pages.

favicon is the final source after explicit-favicon and icon-selection precedence. Landing-page integrations can use this accessor and link to the server's root-level /favicon.ico route without reading private configuration or depending on the landing/view layers.

Returns ServerBranding
Example
```
if (server.branding.favicon) {
  console.log("Browser favicon: /favicon.ico");
}
```
- Defined in server.ts:577

host

get host(): string | undefined
Configured bind host, before CLI and environment overrides.

Returns string | undefined
- Defined in server.ts:553

port

get port(): number | undefined
Configured bind port, before CLI and environment overrides.

Returns number | undefined
- Defined in server.ts:558

Methods

__primeSkills

__primeSkills(snapshot: SkillsSnapshot | undefined): void
String-keyed tooling alias for registerSkills.
Parameters
- snapshot: SkillsSnapshot | undefined
Returns void
- Defined in server.ts:768

close

close(): Promise<void>
Abort in-flight MCP exchanges and stop the HTTP listener.

A closed server is done for good — the underlying MCP handler stays closed, so listen()/fetch() cannot revive it. Create a new instance to serve again.

Returns Promise<void>
- Defined in server.ts:1198

getHandler

getHandler(): (
    ...args: [
        request: Request,
        env?: {}
        | TEnv["Bindings"],
        executionCtx?: ExecutionContext,
    ],
) => Promise<Response>
Returns (
    ...args: [
        request: Request,
        env?: {}
        | TEnv["Bindings"],
        executionCtx?: ExecutionContext,
    ],
) => Promise<Response>
- - (
        ...args: [
            request: Request,
            env?: {}
            | TEnv["Bindings"],
            executionCtx?: ExecutionContext,
        ],
    ): Promise<Response>
  - Canonical Web-standard handler for edge runtimes and framework mounting.
    Parameters
    
    ...args: [request: Request, env?: {} | TEnv["Bindings"], executionCtx?: ExecutionContext]
    Returns Promise<Response>
    Example
    export default server; // or: export const POST = server.fetch;
Deprecated
Use MCPServer.fetch directly.
- Defined in server.ts:582

listen

listen(
port?: number | undefined,
options?: ListenOptions,
): Promise<{ port: number; url: string }>
Serve over HTTP on Node. Pass port 0 for an ephemeral port. Port precedence is the argument, PORT, config.port, then 3000; host precedence is options.host, HOST, config.host, then 127.0.0.1.

Localhost-class binds get DNS-rebinding Host protection automatically. Origin validation is off unless allowedOrigins is set. To serve publicly set host: "0.0.0.0"; behind a platform edge that is all that's needed, and allowedHosts restricts direct exposure (additive — localhost-class values stay allowed).

With OAuth and no explicit resource or MCP_URL, a localhost listener derives its protected-resource URL from the actual bound port. Mounting therefore waits for the listener callback (especially for port 0), and requests accepted before then are queued. Public/wildcard listeners must configure the resource before calling this method.
Parameters
- port: number | undefined = undefined
- options: ListenOptions = {}
Returns Promise<{ port: number; url: string }>

Throws
If called on a localhost-class bind after MCPServer.fetch already mounted the app without Host validation.
- Defined in server.ts:1115

notifyPromptsChanged

notifyPromptsChanged(): Promise<void>
Publish a prompts-list change to v2 clients with active subscriptions.

Returns Promise<void>
Example
```
await server.notifyPromptsChanged();
```
- Defined in server.ts:1062

notifyResourcesChanged

notifyResourcesChanged(): Promise<void>
Publish a resources-list change to v2 clients with active subscriptions.

Returns Promise<void>
Example
```
await server.notifyResourcesChanged();
```
- Defined in server.ts:1075

notifyResourceUpdated

notifyResourceUpdated(uri: string): Promise<void>
Publish a resource update to subscribed v2 clients.
Parameters
- uri: string
  Resource URI whose representation changed.
Returns Promise<void>
Example
```
await server.notifyResourceUpdated("config://settings");
```
- Defined in server.ts:1090

notifyToolsChanged

notifyToolsChanged(): Promise<void>
Publish a tools-list change to v2 clients with active subscriptions.

Returns Promise<void>
Example
```
await server.notifyToolsChanged();
```
- Defined in server.ts:1049

on

on<P extends McpEventPattern>(
pattern: P,
handler: McpEventListenerFnFor<P, TEnv>,
): this
Register a read-only MCP observer. Unlike MCPServer.use, listeners cannot block, override, or mutate params. Throwing is logged and does not fail the request.

Append :complete to run after the handler (for example mcp:tools/call:complete).
Type Parameters
- P extends McpEventPattern
Parameters
- pattern: P
- handler: McpEventListenerFnFor<P, TEnv>
Returns this
Example
```
server.on("mcp:tools/call", (ctx) => {
  metrics.increment("tools.call", { tool: ctx.params.name });
});
```
- Defined in server.ts:1005

prompt

prompt<T extends PromptDefinition>(
definition: T,
callback: PromptCallback<InferPromptInput<T>, TUser, HasOAuth<TUser>, TEnv>,
): this
Register a prompt template. Schema fields wrapped with completable() gain autocomplete via completion/complete.
Type Parameters
- T extends PromptDefinition
Parameters
- definition: T
- callback: PromptCallback<InferPromptInput<T>, TUser, HasOAuth<TUser>, TEnv>
Returns this
- Defined in server.ts:844

proxy

proxy(servers: Record<string, ProxyServerConfig>): Promise<void>
Compose upstream MCP servers into this server.

A name-keyed HTTP config creates upstream connections through the optional @mcp-use/client v2 peer. Each key automatically namespaces its mounted tools, resources, and prompts. You may instead pass an existing ready ProxyConnection; its negotiated server name becomes the namespace and the connection remains caller-owned. Anonymous connections cannot use this overload because they do not provide a namespace.

Connection, introspection, and collision failures are diagnosed and skipped without discarding capabilities that can be mounted.
Parameters
- servers: Record<string, ProxyServerConfig>
  Namespace-keyed upstream HTTP connection settings.
Returns Promise<void>
Throws
If @mcp-use/client is not installed or the server already started or closed.
Example
```
await server.proxy({
  weather: {
    url: "https://weather.example.com/mcp",
    authToken: process.env.WEATHER_MCP_TOKEN,
  },
});
```
- Defined in server.ts:889
proxy(connection: ProxyConnection): Promise<void>
Mount an existing ready @mcp-use/client v2 connection.
Parameters
- connection: ProxyConnection
  Ready connection to introspect and forward through. The connection's negotiated server name automatically namespaces every mounted capability. Anonymous connections are rejected because they do not provide a namespace. Introspection and collision failures are diagnosed and skipped without discarding capabilities that can be mounted.
Returns Promise<void>
Throws
If the server already started or closed.
Example
```
const connection = await client.connect("database");
await server.proxy(connection);
```
- Defined in server.ts:907

resource

resource(
definition: ResourceDefinition,
callback: ResourceCallback<TUser, HasOAuth<TUser>, TEnv>,
): this
Register a static resource readable at definition.uri.
Parameters
- definition: ResourceDefinition
- callback: ResourceCallback<TUser, HasOAuth<TUser>, TEnv>
Returns this
- Defined in server.ts:792

resourceTemplate

resourceTemplate<const TUriTemplate extends string>(
    definition: ResourceTemplateDefinition<TUriTemplate>,
    callback: ResourceTemplateCallback<
        string extends TUriTemplate
            ? Record<TUriTemplate, TemplateVariableValue>
            : { [K in string]: TemplateVariableValue },
        TUser,
        HasOAuth<TUser>,
        TEnv,
    >,
): this
Register a parameterized resource. Reads matching uriTemplate invoke the callback with the extracted variables.

The const type parameter keeps uriTemplate a string literal during inference (plain generic inference widens object-literal properties to string), which is what lets InferTemplateParams type the callback's params from the template's variables.
Type Parameters
- const TUriTemplate extends string
Parameters
- definition: ResourceTemplateDefinition<TUriTemplate>
- callback: ResourceTemplateCallback<
      string extends TUriTemplate
          ? Record<TUriTemplate, TemplateVariableValue>
          : { [K in string]: TemplateVariableValue },
      TUser,
      HasOAuth<TUser>,
      TEnv,
  >
Returns this
- Defined in server.ts:813

settings

settings<const Fields extends SettingsFields>(
options: SettingsRegistration<Fields, TUser, HasOAuth<TUser>, TEnv>,
): void
Register one native plugin settings read/update pair before starting the server.

Callbacks receive the same request context and OAuth guarantees as ordinary authenticated tools. They own authorization, defaults, persistence, atomic partial updates, and cross-field validation. The framework validates field values and replays both tools and the capability on every request-scoped server.
Type Parameters
- const Fields extends SettingsFields
Parameters
- options: SettingsRegistration<Fields, TUser, HasOAuth<TUser>, TEnv>
Returns void

Throws
When already registered, started, field schemas are unsupported, or either tool name collides with an existing registration.
- Defined in server.ts:655

tool

tool<const T extends ToolDefinition>(
    definition: T,
    callback: ToolCallback<
        InferToolInput<T>,
        InferToolOutput<T>,
        TUser,
        ToolOAuthMode<TUser, DefinitionSecuritySchemes<T>>,
        TEnv,
    >,
): ToolRef<InferToolName<T>, InferToolInput<T>, InferToolOutput<T>>
Register a tool. Input is validated against inputSchema before the callback runs; results carrying structuredContent are type-checked against outputSchema at the callback's return position.

Assign static registrations to exported constants so mcp-env.d.ts can expose their ToolRef types to views: export const search = server.tool(...).

ctx.auth is required in the callback unless definition.securitySchemes includes noauth.
Type Parameters
- const T extends ToolDefinition
Parameters
- definition: T
- callback: ToolCallback<
      InferToolInput<T>,
      InferToolOutput<T>,
      TUser,
      ToolOAuthMode<TUser, DefinitionSecuritySchemes<T>>,
      TEnv,
  >
Returns ToolRef<InferToolName<T>, InferToolInput<T>, InferToolOutput<T>>
A ToolRef carrying the tool name and phantom types for inference-based view typing.

Throws
TypeError When definition.securitySchemes is invalid for this server.
- Defined in server.ts:603

use

use<
    P extends
        | "mcp:*"
        | "mcp:prompts/get"
        | "mcp:prompts/list"
        | "mcp:resources/list"
        | "mcp:resources/read"
        | "mcp:tools/call"
        | "mcp:tools/list",
>(
    pattern: P,
    handler: McpMiddlewareFnFor<P, TEnv>,
): this
Register HTTP middleware or typed MCP operation middleware.

MCP patterns always use an mcp: prefix (for example mcp:tools/call, mcp:*). Every other overload is Hono middleware and may target all routes or a path pattern.

Exact methods may transform their typed result. The global mcp:* pattern is pass-through middleware. Middleware runs in registration order; call next() to continue the chain.
Type Parameters
- P extends
      | "mcp:*"
      | "mcp:prompts/get"
      | "mcp:prompts/list"
      | "mcp:resources/list"
      | "mcp:resources/read"
      | "mcp:tools/call"
      | "mcp:tools/list"
Parameters
- pattern: P
- handler: McpMiddlewareFnFor<P, TEnv>
Returns this
Example
```
server.use("/api/*", async (c, next) => {
  c.set("requestId", crypto.randomUUID());
  await next();
});

server.use("mcp:tools/call", async (ctx, next) => {
  console.log(`Calling tool: ${ctx.params.name}`);
  return next();
});
```
- Defined in server.ts:955
use(handler: MiddlewareHandler<TEnv>): this
Register HTTP middleware or typed MCP operation middleware.

MCP patterns always use an mcp: prefix (for example mcp:tools/call, mcp:*). Every other overload is Hono middleware and may target all routes or a path pattern.

Exact methods may transform their typed result. The global mcp:* pattern is pass-through middleware. Middleware runs in registration order; call next() to continue the chain.
Parameters
- handler: MiddlewareHandler<TEnv>
Returns this
Example
```
server.use("/api/*", async (c, next) => {
  c.set("requestId", crypto.randomUUID());
  await next();
});

server.use("mcp:tools/call", async (ctx, next) => {
  console.log(`Calling tool: ${ctx.params.name}`);
  return next();
});
```
- Defined in server.ts:959
use(path: "*" | `/${string}`, ...handlers: MiddlewareHandler<TEnv>[]): this
Register HTTP middleware or typed MCP operation middleware.

MCP patterns always use an mcp: prefix (for example mcp:tools/call, mcp:*). Every other overload is Hono middleware and may target all routes or a path pattern.

Exact methods may transform their typed result. The global mcp:* pattern is pass-through middleware. Middleware runs in registration order; call next() to continue the chain.
Parameters
- path: "*" | `/${string}`
- ...handlers: MiddlewareHandler<TEnv>[]
Returns this
Example
```
server.use("/api/*", async (c, next) => {
  c.set("requestId", crypto.randomUUID());
  await next();
});

server.use("mcp:tools/call", async (ctx, next) => {
  console.log(`Calling tool: ${ctx.params.name}`);
  return next();
});
```
- Defined in server.ts:960

`Static`fromOpenAPI

fromOpenAPI(options: FromOpenAPIOptions): MCPServer
Create an MCP server from a parsed, bundled OpenAPI document.

Each included OpenAPI operation becomes a tool that validates its input, calls the matching upstream HTTP endpoint, and returns the response using the SDK's raw tool-result shape. External $ref values are not fetched; bundle the document before passing it in.
Parameters
- options: FromOpenAPIOptions
  OpenAPI document, operation filters, upstream URL, and request authentication options.
Returns MCPServer
An unauthenticated MCP server populated with generated tools.
Example
```
const spec = await fetch("https://api.example.com/openapi.json")
  .then((response) => response.json());
const server = MCPServer.fromOpenAPI({ spec });
await server.listen(3000);
```
- Defined in server.ts:489

Class MCPServer<TUser, TEnv>

Example

Type Parameters

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns MCPServer<TUser, TEnv>

Properties

Readonlyall

Readonlyapp

Readonlydelete

Readonlyfetch

Example

Readonlyget

Readonlypatch

Readonlypost

Readonlyput

Accessors

basePath

Returns string

branding

Returns ServerBranding

Example

host

Returns string | undefined

port

Returns number | undefined

Methods

__primeSkills

Parameters

Returns void

close

Returns Promise<void>

getHandler

Returns ( ...args: [ request: Request, env?: {} | TEnv["Bindings"], executionCtx?: ExecutionContext, ],) => Promise<Response>

Parameters

Returns Promise<Response>

Example

Deprecated

listen

Parameters

Returns Promise<{ port: number; url: string }>

Throws

notifyPromptsChanged

Returns Promise<void>

Example

notifyResourcesChanged

Returns Promise<void>

Example

notifyResourceUpdated

Parameters

Returns Promise<void>

Example

notifyToolsChanged

Returns Promise<void>

Example

on

Type Parameters

Parameters

Returns this

Example

prompt

Type Parameters

Parameters

Returns this

proxy

Parameters

Returns Promise<void>

Throws

Example

Parameters

Returns Promise<void>

Throws

Example

`Readonly`all

`Readonly`app

`Readonly`delete

`Readonly`fetch

`Readonly`get

`Readonly`patch

`Readonly`post

`Readonly`put

Returns (
...args: [
request: Request,
env?: {}
| TEnv["Bindings"],
executionCtx?: ExecutionContext,
],
) => Promise<Response>

`Static`fromOpenAPI