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

# McpServer

> Build and run a Skybridge MCP server

`McpServer` is the root of your app: an [Express](https://expressjs.com/)-backed server whose methods return the server itself, so you chain your [tool](/build/tools) registrations off it and export the resulting type for [`generateHelpers`](/api-reference/generate-helpers).

## Example

A server registers one tool, exports its type for the typed client hooks, and starts listening.

```ts server.ts theme={null}
import { McpServer } from "skybridge/server";

const server = new McpServer({ name: "shop", version: "1.0" }).registerTool(
  /* ... */
);

export type AppType = typeof server; // generateHelpers reads your tools from this

await server.run();
```

## Constructor

```ts theme={null}
new McpServer(
  serverInfo: { name: string; version: string },
  options?: ServerOptions,
  skybridgeOptions?: SkybridgeServerOptions,
);
```

* **`serverInfo`** your server's `name` and `version`.
* **`options`** forwarded to the MCP SDK server.
* **`skybridgeOptions`** Skybridge-specific configuration:

```ts theme={null}
type SkybridgeServerOptions = {
  json?: JsonOptions;
  oauth?: OAuthConfig;
};
```

`json` tunes the [`express.json()`](https://expressjs.com/en/5x/api/express/#expressjsonoptions) parser Skybridge pre-applies, for example to raise the default 100kb body-size limit.

`oauth` is an [`OAuthConfig`](/api-reference/custom-provider#returns), usually from [`customProvider`](/api-reference/custom-provider) or a branded provider. When set, it mounts the well-known OAuth metadata and bearer-token verification on `/mcp`.

## Properties

### `express`

The underlying Express app, for custom routes, middleware, and settings. Register handlers before `run()`.

<Info>
  [Alpic Cloud](https://alpic.ai/solutions/cloud) routes traffic only to `/mcp`. Custom routes work locally and on self-hosted deployments.
</Info>

## Methods

Every method returns the server, so calls chain.

### `registerTool`

```ts theme={null}
server.registerTool(config, handler): this;
```

Registers a tool, optionally bound to a view. See [registerTool](/api-reference/register-tool) for the full config and handler.

### `use`

```ts theme={null}
server.use(...handlers: RequestHandler[]): this;
server.use(path: string, ...handlers: RequestHandler[]): this;
```

Registers [Express middleware](https://expressjs.com/en/guide/using-middleware/) on the underlying app, optionally scoped to a path. Mirrors `app.use`.

### `useOnError`

```ts theme={null}
server.useOnError(...handlers: ErrorRequestHandler[]): this;
server.useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
```

Registers an [Express error handler](https://expressjs.com/en/guide/error-handling.html), optionally path-scoped, to run after the `/mcp` route. A default handler runs last, responding with a 500 [JSON-RPC](https://www.jsonrpc.org/) error when nothing else has sent a response.

### `mcpMiddleware`

```ts theme={null}
server.mcpMiddleware(handler: McpMiddlewareFn): this;
server.mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn): this;
```

Wraps MCP requests and notifications: each middleware runs `(request, extra, next)`, can inspect or short-circuit the call, and invokes `next()` to continue. Register it before `run()` or `connect()`; middleware runs in registration order, outermost first. An optional `filter` scopes which methods it runs for.

| Filter                             | Matches                   |
| ---------------------------------- | ------------------------- |
| `"tools/call"`                     | that exact method         |
| `"tools/*"`                        | any method under `tools/` |
| `"request"`                        | all requests              |
| `"notification"`                   | all notifications         |
| `["tools/call", "resources/read"]` | any pattern in the list   |

```ts theme={null}
server.mcpMiddleware("request", (request, extra, next) => {
  console.log(`[MCP] ${request.method}`, request.params);
  return next();
});
```

### `run`

```ts theme={null}
server.run(): Promise<{ fetch: (...args: unknown[]) => unknown } | Express | undefined>;
```

Starts the HTTP server: applies your middleware, mounts `/mcp`, and listens (default port `3000`). On serverless platforms, export what it returns so the platform can route requests to it. See [Deploy](/ship/deploy) for the per-platform setup.

<CardGroup cols={3}>
  <Card title="registerTool" icon="wrench" href="/api-reference/register-tool">
    Define the tools and views the server exposes
  </Card>

  <Card title="generateHelpers" icon="wand-sparkles" href="/api-reference/generate-helpers">
    Turn `AppType` into typed client hooks
  </Card>

  <Card title="requireBearerAuth" icon="lock" href="/api-reference/require-bearer-auth">
    Require or optionally accept a signed-in user
  </Card>
</CardGroup>