> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCPServer

> Build MCP servers with tools, resources, and prompts API Documentation

**Source Code**

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](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/mcp-server.ts)](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).

```ts theme={null}
import { MCPServer } from "mcp-use/server";
```

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

```ts wrap theme={null}
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();
```

**Constructor return type**

`new MCPServer(config)` returns an `McpServerInstance`, a value that is simultaneously the `MCPServer` class, the [Hono](https://hono.dev) 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**

> **config** `ServerConfig` *required*
>
> Server configuration object (see fields below).

The most common `ServerConfig` fields:

> **config.name** `string` *required*
>
> Unique server name displayed to clients.
>
> **config.version** `string` *required*
>
> Semantic version of the server (e.g. "1.0.0").
>
> **config.description** `string | undefined` (default: undefined)
>
> Human-readable description shown to clients during discovery.
>
> **config.instructions** `string | undefined` (default: undefined)
>
> Server-wide guidance for AI models, returned during MCP initialization.
>
> **config.host** `string | undefined` (default: "localhost")
>
> Hostname used for widget URLs and server endpoints.
>
> **config.baseUrl** `string | undefined` (default: undefined)
>
> Full public base URL (overrides `host:port` for widget and OAuth URLs). Use when behind a reverse proxy.
>
> **config.oauth** `OAuthProvider | undefined` (default: undefined)
>
> OAuth provider configuration. When present, the instance is typed as `McpServerInstance<true>`.
>
> **config.cors** `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.
>
> **config.allowedOrigins** `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).
>
> **config.stateless** `boolean | undefined` (default: undefined)
>
> Force stateless (no session tracking) or stateful mode. Auto-detected when omitted: stateless for Deno, stateful for Node.js.
>
> **config.sessionIdleTimeoutMs** `number | undefined` (default: 86400000)
>
> Idle timeout for sessions in milliseconds (default: 86400000, one day).

**Signature**

```ts wrap theme={null}
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** `ToolDefinition` *required*
>
> Tool configuration (name, description, schema/inputs, annotations, etc.).
>
> **callback** `ToolCallback | undefined` (default: undefined)
>
> Async handler that receives the validated input (and a context object) and returns a tool result.

**Returns**

> **returns** `this`

**Example**

```ts wrap theme={null}
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**

```ts wrap theme={null}
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** `ResourceDefinition` *required*
>
> Resource configuration (name, uri, description, mimeType).
>
> **callback** `ReadResourceCallback | undefined` (default: undefined)
>
> Async handler returning the resource content.

**Returns**

> **returns** `this`

**Example**

```ts wrap theme={null}
import { markdown } from "mcp-use/server";

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

**Signature**

```ts wrap theme={null}
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**

> **templateDefinition** `ResourceTemplateDefinition` *required*
>
> Template configuration (name, uriTemplate, description, mimeType, callbacks).
>
> **callback** `ReadResourceTemplateCallback | undefined` (default: undefined)
>
> Async handler receiving the resolved `URL` and the extracted params.

**Returns**

> **returns** `this`

**Example**

```ts wrap theme={null}
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**

```ts wrap theme={null}
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** `PromptDefinition` *required*
>
> Prompt configuration (name, description, schema).
>
> **callback** `PromptCallback | undefined` (default: undefined)
>
> Async handler that returns the prompt messages.

**Returns**

> **returns** `this`

**Example**

```ts wrap theme={null}
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**

```ts wrap theme={null}
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](https://docs.mcp-use.com/v1/typescript/api-reference/server/widgets.md).

**Parameters**

> **definition** `UIResourceDefinition` *required*
>
> UI resource configuration (name, uri, and the widget source such as `html`, a component, or an external URL). See [UIResourceDefinition](https://docs.mcp-use.com/v1/typescript/api-reference/server/resources.md).

**Returns**

> **returns** `this`

**Example**

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

**Signature**

```ts wrap theme={null}
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**

> **uri** `string` *required*
>
> The URI of the resource that was updated.

**Returns**

> **returns** `Promise\<void\>`

**Example**

```ts wrap theme={null}
// After updating a resource, notify subscribers
await server.notifyResourceUpdated("file:///path/to/resource.txt");
```

**Signature**

```ts wrap theme={null}
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**

> **port** `number | undefined` (default: 3000)
>
> Port to listen on. When omitted, falls back to `PORT`, `config.port`, then 3000.
>
> **options** `ListenOptions` (default: \{})
>
> Optional listener settings, including `host`. Host falls back to `HOST`, `config.host`, then `127.0.0.1`.

**Returns**

> **returns** `Promise\<\{ port: number; url: string \}\>`

**Example**

```ts wrap theme={null}
await server.listen(3000);
// Server running at: http://localhost:3000
// MCP endpoint:      http://localhost:3000/mcp
```

**Signature**

```ts wrap theme={null}
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**

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

**Returns**

> **returns** `Promise\<void\>`

**Example**

```ts wrap theme={null}
// 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**

```ts wrap theme={null}
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**

> **options** `FromOpenAPIOptions` *required*
>
> OpenAPI options (see fields below).
>
> **options.spec** `OpenAPIDocument` *required*
>
> The parsed OpenAPI document.
>
> **options.baseUrl** `string | undefined` (default: undefined)
>
> Base URL for the generated HTTP requests.
>
> **options.name** `string | undefined` (default: spec.info.title)
>
> Server name override.
>
> **options.version** `string | undefined` (default: spec.info.version)
>
> Server version override (falls back to "1.0.0").
>
> **options.auth** `OpenAPIAuth | undefined` (default: undefined)
>
> Bearer or header auth applied to generated requests.
>
> **options.headers** `Record\<string, string\> | undefined` (default: undefined)
>
> Extra headers sent with every request.
>
> **options.tags** `string[] | undefined` (default: undefined)
>
> Only include operations matching these tags.
>
> **options.exclude** `OpenAPIExcludeRule[] | undefined` (default: undefined)
>
> Rules to exclude operations by operationId, path, method, or tags.
>
> **options.fetch** `typeof fetch | undefined` (default: undefined)
>
> Custom fetch implementation.

**Returns**

> **returns** `McpServerInstance\<false\>`

**Signature**

```ts wrap theme={null}
static fromOpenAPI(options: FromOpenAPIOptions): McpServerInstance<false>
```

### getPackageVersion

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

**Returns**

> **returns** `string`

**Example**

```ts wrap theme={null}
console.log(`mcp-use version: ${MCPServer.getPackageVersion()}`);
```

**Signature**

```ts wrap theme={null}
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**

```ts wrap theme={null}
type McpServerInstance<HasOAuth extends boolean = false> = WithMcpUse & MCPServerClass<HasOAuth> & HonoType
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.