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:473

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:513

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:542

host

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

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

port

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

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

Methods

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:1032

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:547

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:950

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:900

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:912

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:926

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:888

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:855

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:696

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.

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:740
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. 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:757

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:644

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:665

tool

tool<const T extends ToolDefinition>(
    definition: T,
    callback: ToolCallback<
        InferToolInput<T>,
        InferToolOutput<T>,
        TUser,
        HasOAuth<TUser>,
        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(...).
Type Parameters
- const T extends ToolDefinition
Parameters
- definition: T
- callback: ToolCallback<
      InferToolInput<T>,
      InferToolOutput<T>,
      TUser,
      HasOAuth<TUser>,
      TEnv,
  >
Returns ToolRef<InferToolName<T>, InferToolInput<T>, InferToolOutput<T>>
A ToolRef carrying the tool name and phantom types for inference-based view typing.
- Defined in server.ts:563

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:805
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:809
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:810

`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:455

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

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

resource

Parameters

Returns this

`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