MCPServer

View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/mcp-server.ts

Full MCP (Model Context Protocol) server built on the Hono web framework. It combines MCP protocol handling with an HTTP server so you can declare tools, resources, and prompts, then serve them to any MCP client. Run it standalone with listen(), or get a handler for serverless platforms (Cloudflare Workers, Vercel Edge, Deno).

import { MCPServer } from "mcp-use/server";

A minimal server (from the basic/simple example):

import { MCPServer, text } from "mcp-use/server";

const server = new MCPServer({
  name: "simple-example-server",
  version: "1.0.0",
  description: "A simple MCP server example",
});

server.tool(
  {
    name: "hello-world",
    description: "A simple tool that returns hello world",
  },
  async () => text("Hello World!")
);

// Start the server (MCP endpoints auto-mounted at /mcp)
await server.listen();

new MCPServer(config) returns an McpServerInstance, a value that is simultaneously the MCPServer class, the Hono app, and an mcp-use helper surface. That means server.tool(...) (MCP) and server.get('/health', ...) (Hono) both work on the same object. The exact return type is McpServerInstance<true> when oauth is configured and McpServerInstance<false> otherwise.

Constructor

Creates a new server instance. Initializes the native MCP server from the official SDK, creates the Hono application, sets up OAuth if configured, configures session management (stateful or stateless), and wraps the registration methods for multi-session support. Stateless mode is auto-detected (Deno defaults to stateless, Node.js to stateful) when stateless is not set. Parameters

ServerConfig
required
Server configuration object (see fields below).

The most common ServerConfig fields:

string
required
Unique server name displayed to clients.

string
required
Semantic version of the server (e.g. “1.0.0”).

string | undefined
default:"undefined"
Human-readable description shown to clients during discovery.

string | undefined
default:"undefined"
Server-wide guidance for AI models, returned during MCP initialization.

string | undefined
default:"\"localhost\""
Hostname used for widget URLs and server endpoints.

string | undefined
default:"undefined"
Full public base URL (overrides host:port for widget and OAuth URLs). Use when behind a reverse proxy.

OAuthProvider | undefined
default:"undefined"
OAuth provider configuration. When present, the instance is typed as McpServerInstance<true>.

Partial<Parameters<typeof cors>[0]> | undefined
default:"undefined"
CORS overrides, matching the options accepted by Hono’s cors middleware. Defaults to permissive CORS (origin: "*") for development ergonomics.

string[] | undefined
default:"undefined"
Allowed origins for DNS rebinding protection. When unset, Origin validation is off. When set, validation is enabled (additive to localhost origins).

boolean | undefined
default:"undefined"
Force stateless (no session tracking) or stateful mode. Auto-detected when omitted: stateless for Deno, stateful for Node.js.

number | undefined
default:"86400000"
Idle timeout for sessions in milliseconds (default: 86400000, one day).

Signature

constructor(config: ServerConfig)

Methods

tool

Registers a tool that MCP clients can call. The definition supplies name and description; pass a Zod schema (or inputs) to validate arguments, and an optional callback that returns the tool result. Returns the server instance so calls can be chained. Argument types are inferred from the definition, so the callback parameters are fully typed. Parameters

ToolDefinition
required
Tool configuration (name, description, schema/inputs, annotations, etc.).

ToolCallback | undefined
default:"undefined"
Async handler that receives the validated input (and a context object) and returns a tool result.

Returns

this

Example

import { z } from "zod";
import { text } from "mcp-use/server";

server.tool(
  {
    name: "add",
    description: "Add two numbers",
    schema: z.object({ a: z.number(), b: z.number() }),
  },
  async ({ a, b }) => text(String(a + b))
);

Signature

tool: <T extends ToolDefinition>(toolDefinition: T, callback?: ToolCallback<InferToolInput<T>, InferToolOutput<T>, HasOAuth>) => this

resource

Registers a static resource that clients can read by its URI. A resource represents data or content (a file, a config blob, an API response). Returns the server instance for chaining. The mimeType defaults to "text/plain" when omitted. Parameters

ResourceDefinition
required
Resource configuration (name, uri, description, mimeType).

ReadResourceCallback | undefined
default:"undefined"
Async handler returning the resource content.

Returns

this

Example

import { markdown } from "mcp-use/server";

server.resource(
  {
    name: "greeting",
    uri: "app://greeting",
    title: "Greeting Message",
  },
  async () => markdown("# Hello from mcp-use!")
);

Signature

resource: (resourceDefinition: ResourceDefinition | ResourceDefinitionWithoutCallback, callback?: ReadResourceCallback<HasOAuth>) => this

resourceTemplate

Registers a resource template for parameterized resources. Clients read URIs that match a uriTemplate (for example docs://{topic}); the template parameters are extracted and passed to the callback. Optional callbacks.complete provides autocomplete suggestions per parameter. Returns the server instance for chaining. Parameters

ResourceTemplateDefinition
required
Template configuration (name, uriTemplate, description, mimeType, callbacks).

ReadResourceTemplateCallback | undefined
default:"undefined"
Async handler receiving the resolved URL and the extracted params.

Returns

this

Example

import { markdown, error } from "mcp-use/server";

server.resourceTemplate(
  {
    name: "documentation",
    uriTemplate: "docs://{topic}",
    title: "Documentation",
    description: "Get documentation by topic",
    mimeType: "text/markdown",
    callbacks: {
      complete: {
        topic: ["api", "auth", "getting-started", "troubleshooting"],
      },
    },
  },
  async (uri: URL, params: Record<string, string>) => {
    const docs: Record<string, string> = {
      api: "# API Docs",
      auth: "# Auth Guide",
    };
    const content = docs[params.topic];
    if (!content) {
      return error(`Topic not found: ${params.topic}`);
    }
    return markdown(content);
  }
);

Signature

resourceTemplate: <T extends ResourceTemplateDefinition>(templateDefinition: T, callback?: ReadResourceTemplateCallback<InferTemplateParams<T>, HasOAuth>) => this

prompt

Registers a reusable prompt template that clients can request. Prompts can accept arguments (validated by a Zod schema) and return formatted messages ready to send to an LLM. Returns the server instance for chaining. Parameters

PromptDefinition
required
Prompt configuration (name, description, schema).

PromptCallback | undefined
default:"undefined"
Async handler that returns the prompt messages.

Returns

this

Example

import { z } from "zod";
import { text } from "mcp-use/server";

server.prompt(
  {
    name: "greeting",
    description: "A simple prompt that returns a greeting",
    schema: z.object({ name: z.string() }),
  },
  async ({ name }) => text(`Hello, ${name}!`)
);

Signature

prompt: <T extends PromptDefinition>(promptDefinition: T, callback?: PromptCallback<InferPromptInput<T>, HasOAuth>) => this

uiResource

Registers a UI resource for interactive widgets (MCP Apps). UI resources serve interactive components that compatible clients (such as ChatGPT with the Apps SDK, or Claude) can render. Returns the server instance for chaining. This is a declarative wrapper over the lower-level builders in the Widgets and MCP Apps reference. Parameters

UIResourceDefinition
required
UI resource configuration (name, uri, and the widget source such as html, a component, or an external URL). See UIResourceDefinition.

Returns

this

Example

server.uiResource({
  name: "chart-viewer",
  uri: "ui://chart",
  html: "<div>Chart goes here</div>",
});

Signature

uiResource(definition: UIResourceDefinition): this

notifyResourceUpdated

Notifies subscribed clients that a resource has changed. Sends a notifications/resources/updated message to every session that called resources/subscribe for the given URI. Can be called from a tool handler or any async context. Resolves once all notifications have been sent. Parameters

string
required
The URI of the resource that was updated.

Returns

Promise<void>

Example

// After updating a resource, notify subscribers
await server.notifyResourceUpdated("file:///path/to/resource.txt");

Signature

notifyResourceUpdated(uri: string): Promise<void>

listen

Starts the HTTP server. Mounts MCP protocol endpoints, widget routes, and OAuth routes (if configured), then begins listening. The Inspector is mounted by mcp-use dev, or explicitly on a built server with mcp-use start --with-inspector. Resolves once the server is listening. During HMR reload (when the CLI manages the lifecycle) this is a no-op. Address resolution is explicit value, environment variable, server configuration, then default: the port argument → PORT → config.port → 3000; options.host → HOST → config.host → 127.0.0.1. The CLI supplies explicit values only when its corresponding flag is present. Parameters

number | undefined
default:"3000"
Port to listen on. When omitted, falls back to PORT, config.port, then 3000.

ListenOptions
default:"{}"
Optional listener settings, including host. Host falls back to HOST, config.host, then 127.0.0.1.

Returns

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

Example

await server.listen(3000);
// Server running at: http://localhost:3000
// MCP endpoint:      http://localhost:3000/mcp

Signature

listen(port?: number, options?: ListenOptions): Promise<{ port: number; url: string }>

proxy

Mounts one or more remote HTTP MCP servers onto this server. It introspects each remote server’s tools, static resources, and prompts and registers them natively, so this server acts as a gateway. Config-map keys automatically namespace capabilities; an existing MCPConnection uses its negotiated server name. Connection, introspection, and collision failures are reported diagnostically while successfully mountable capabilities remain available. Proxy config accepts caller-managed bearer tokens and authentication headers. It does not expose stdio or automatic OAuth options, and it disables client auto-OAuth internally so proxy setup and server startup never open a browser. Parameters

Record<string, ProxyServerConfig> | ProxyConnection
required
A name-keyed map of HTTP server connection config, or one ready caller-owned connection.

Returns

Promise<void>

Example

// Config keys become namespaces automatically
await server.proxy({
  db: {
    url: "https://database.example.com/mcp",
    authToken: process.env.DATABASE_MCP_TOKEN,
  },
});

// The connection's negotiated server name becomes its namespace
await server.proxy(connection);

Signature

proxy(config: Record<string, ProxyServerConfig> | ProxyConnection): Promise<void>

Static methods

fromOpenAPI

Creates an MCP server from a parsed, bundled OpenAPI document. Each included OpenAPI operation is registered as an MCP tool. The server name defaults to spec.info.title and the version defaults to options.version, then spec.info.version, then "1.0.0". Returns an McpServerInstance<false> (OAuth is not configured by this factory). Parameters

FromOpenAPIOptions
required
OpenAPI options (see fields below).

OpenAPIDocument
required
The parsed OpenAPI document.

string | undefined
default:"undefined"
Base URL for the generated HTTP requests.

string | undefined
default:"spec.info.title"
Server name override.

string | undefined
default:"spec.info.version"
Server version override (falls back to “1.0.0”).

OpenAPIAuth | undefined
default:"undefined"
Bearer or header auth applied to generated requests.

Record<string, string> | undefined
default:"undefined"
Extra headers sent with every request.

string[] | undefined
default:"undefined"
Only include operations matching these tags.

OpenAPIExcludeRule[] | undefined
default:"undefined"
Rules to exclude operations by operationId, path, method, or tags.

typeof fetch | undefined
default:"undefined"
Custom fetch implementation.

Returns

McpServerInstance<false>

Signature

static fromOpenAPI(options: FromOpenAPIOptions): McpServerInstance<false>

getPackageVersion

Returns the installed mcp-use package version string (for example "1.13.2"). Returns

string

Example

console.log(`mcp-use version: ${MCPServer.getPackageVersion()}`);

Signature

static getPackageVersion(): string

Types

McpServerInstance

The runtime type of a value returned by new MCPServer(config). It is an intersection of three surfaces, so a single instance exposes MCP methods, the full Hono app, and the mcp-use helper surface at once. The HasOAuth type parameter is true when oauth is configured in ServerConfig and false otherwise; it flows into the typing of tool, resource, and prompt callbacks (for example, the presence of ctx.auth). Definition

type McpServerInstance<HasOAuth extends boolean = false> = WithMcpUse & MCPServerClass<HasOAuth> & HonoType

Overview

Server

React

Client

Agent

Constructor

Methods

tool

resource

resourceTemplate

prompt

uiResource

notifyResourceUpdated

listen

proxy

Static methods

fromOpenAPI

getPackageVersion

Types

McpServerInstance

​Constructor

​Methods

​tool

​resource

​resourceTemplate

​prompt

​uiResource

​notifyResourceUpdated

​listen

​proxy

​Static methods

​fromOpenAPI

​getPackageVersion

​Types

​McpServerInstance

Constructor

Methods

tool

resource

resourceTemplate

prompt

uiResource

notifyResourceUpdated

listen

proxy

Static methods

fromOpenAPI

getPackageVersion

Types

McpServerInstance