> ## 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.

# ServerConfig

> Configure mcp-use v2 server identity, branding, HTTP routing, logging, and OAuth.

`ServerConfig` is the object you pass to `new MCPServer(...)`. `name` and `version` are required. The v2 server is stateless, uses Hono for HTTP routing, and exposes a Fetch-standard serving boundary; there are no session-store fields on this type.

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

const server = new MCPServer({
  name: "catalog-server",
  title: "Catalog Server",
  version: "1.0.0",
  description: "Search the product catalog.",
  websiteUrl: "https://example.com/catalog",
  icons: [
    { src: "brand/icon.svg", mimeType: "image/svg+xml" },
    {
      src: "brand/icon-32.png",
      mimeType: "image/png",
      sizes: ["32x32"],
    },
  ],
});
```

## Configuration fields

> **name** `string` *required*
>
> Machine-readable server name reported during MCP initialization.

**version** `string` *required*

Server version reported during MCP initialization.

**title** `string`

Human-readable display name. Clients can fall back to `name` when omitted.

**description** `string`

Human-readable description reported in MCP implementation metadata.

**websiteUrl** `string`

Absolute HTTP(S) website or documentation URL reported in MCP implementation metadata. Relative, empty, and non-HTTP(S) values throw at construction.

**icons** `Icon[]`

Official MCP implementation icons. A source can be a path relative to `public/`, an absolute HTTP(S) URL, or an `image/*` data URL. Local paths become request-scoped absolute URLs under `${basePath}/_mcp-use/public/`. An empty array is valid.

**favicon** `string`

Explicit browser favicon source. It accepts the same source forms as `icons` and overrides favicon inference. The server exposes the selected image at the root-level `/favicon.ico` route.

**instructions** `string`

Server-wide guidance surfaced to models by MCP clients.

**basePath** `string` (default: /mcp)

Exact MCP endpoint pathname. It must start with `/` and cannot contain whitespace, `//`, a query, a fragment, or a trailing slash except for `/` itself.

**host** `string` (default: 127.0.0.1)

Hostname used by `listen()`. Set `"0.0.0.0"` for a public bind. `server.fetch` does not bind a socket.

**allowedHosts** `string[]`

Additional Host-header allowlist entries. Values are additive to localhost names and enable Host validation for `server.fetch`.

**allowedOrigins** `string[]`

Additional Origin-header allowlist entries. Values are additive to localhost origins. When omitted, Origin validation is off (SDK-aligned). GET and HEAD skip Origin validation when enabled.

**legacy** `"stateless" | "reject"` (default: stateless)

Serve 2025-era clients through the stateless compatibility path, or reject them for a modern-only server.

**publicLandingPage** `boolean` (default: false)

Expose the HTML landing page without bearer authentication when OAuth is configured. The page remains available for explicit HTML GET/HEAD navigation and MCP protocol requests stay protected.

**cors** `CorsOptions`

Add CORS headers to every mcp-use-owned route. Omit it for no CORS headers; use this alongside `allowedOrigins` when serving browser clients.

**logging** `LoggingOptions`

Configure request logging. Logging is enabled at `info` by default; use `{ enabled: false }`, `debug`, or `trace` as needed.

**requestState** `ServerOptions['requestState']`

Configure integrity verification for `requestState` echoed across `input_required` rounds.

**oauth** `OAuthProvider\<TUser\>`

OAuth resource-server provider. When you supply a non-`never``TUser`, this field becomes required and authenticated callbacks receive `ctx.auth.user`.

## Icon and favicon behavior

When `favicon` is omitted, `icons` selects the browser favicon using the **first icon** in author order.

An empty `icons` array selects no favicon. An explicit empty `favicon` is invalid.

`GET /favicon.ico` and `HEAD /favicon.ico` stay at the domain root even when `basePath` is custom or `/`. Local files and data URLs are served directly. HTTP(S) favicon sources return a `307` redirect; mcp-use never fetches the remote image server-side. Missing local files return `404`.

Local files belong under the project `public/` directory:

```text theme={null}
public/
└── brand/
    ├── icon.svg
    └── icon-32.png
```

`mcp-use build` copies `public/` into the production output even when the server has no views. Local paths cannot start with `/` or contain traversal segments, backslashes, queries, fragments, or empty path segments.

## Type definition

```ts theme={null}
import type { Icon, ServerOptions } from "@modelcontextprotocol/server";
import type { CorsOptions, LoggingOptions } from "mcp-use";
import type { OAuthProvider } from "mcp-use/oauth";

interface BaseServerConfig {
  name: string;
  version: string;
  title?: string;
  description?: string;
  websiteUrl?: string;
  icons?: Icon[];
  favicon?: string;
  instructions?: string;
  basePath?: string;
  host?: string;
  port?: number;
  allowedHosts?: string[];
  allowedOrigins?: string[];
  legacy?: "stateless" | "reject";
  publicLandingPage?: boolean;
  cors?: CorsOptions;
  logging?: LoggingOptions;
  requestState?: ServerOptions["requestState"];
}

type ServerConfig<TUser = never> = BaseServerConfig &
  ([TUser] extends [never]
    ? { oauth?: undefined }
    : { oauth: OAuthProvider<TUser> });
```

`host` and `port` are code-level listener fallbacks. `listen()` and `mcp-use start` use them only after an explicit flag/value and `HOST`/`PORT`; use `port: 0` to request an ephemeral port.

`ServerConfig<TUser>` requires `oauth` when `TUser` is not `never` and rejects it when no authenticated user type is declared.

## Use branding in browser pages

`server.branding` exposes the immutable normalized `favicon`, `icons`, and `websiteUrl` values. Browser shells should link to `/favicon.ico` instead of duplicating selection logic.

```ts theme={null}
if (server.branding.favicon) {
  // Render this in the page head.
  const faviconLink = '<link rel="icon" href="/favicon.ico">';
}
```

The built-in landing page adds this link automatically and displays the selected favicon as its server icon. MCP clients receive `websiteUrl` and `icons` through standard server implementation metadata.

## See also

* [MCPServer](https://docs.mcp-use.com/v1/typescript/api-reference/server/mcp-server.md) for server lifecycle and registration methods.
* [Authentication](https://docs.mcp-use.com/v1/typescript/server/authentication.md) for OAuth provider setup.


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