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

# McpServer

> The server your handler registers tools on

`McpServer` is the server instance a [`Skybridge`](https://docs.skybridge.tech/api-reference/skybridge) app hands to its `handler`, once per request. Its registration methods return the server itself, so you chain them and return the chain: that return value is what carries your tool types into `typeof app`.

## Example

The handler registers two tools and a middleware, and returns the chain.

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

export const app = new Skybridge({
  name: "shop",
  version: "1.0",
  handler: (server) =>
    server
      .registerTool(/* search-products */)
      .registerTool(/* create-checkout */)
      .mcpMiddleware("request", (request, extra, next) => {
        console.log(`[MCP] ${request.method}`);
        return next();
      }),
});
```

Define the handler inline, as above: that is what lets TypeScript infer the claims your `oauth` verifier produces into `extra.http.authInfo.extra`, and the tool registry into `typeof app`. Splitting the tool definitions across files is still easy, since each `registerTool` callback is an ordinary function you can import.

> [!WARNING]
>
> The handler runs for every request, so anything in it other than registration runs per request too. Move one-time work (a pool, a client, a file read) into [`setup`](https://docs.skybridge.tech/api-reference/skybridge#setup), whose result is the handler's second argument.

## 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](https://docs.skybridge.tech/api-reference/register-tool.md) for the full config and handler.

### `registerMentions`

```ts theme={null}
server.registerMentions(config): this;
```

Registers the ChatGPT composer at-mention search. See [registerMentions](https://docs.skybridge.tech/api-reference/register-mentions.md).

### `registerEvent`

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

Declares an event type hosts can subscribe to, and hands each subscription to your hooks. Experimental. See [registerEvent](https://docs.skybridge.tech/api-reference/register-event.md).

### `registerFileViewer`

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

Registers a ChatGPT desktop file viewer. See [registerFileViewer](https://docs.skybridge.tech/api-reference/register-file-viewer.md).

### `registerSettings`

```ts theme={null}
server.registerSettings(config): this;
```

Registers your app's settings page in ChatGPT. See [registerSettings](https://docs.skybridge.tech/api-reference/register-settings.md).

### `registerResource`, `registerPrompt`

Inherited from the MCP SDK's [`McpServer`](https://github.com/modelcontextprotocol/typescript-sdk), with the same signatures. Views register their own resources, so you only need `registerResource` for data you expose directly.

### `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. 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();
});
```

### `getToolError`

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

getToolError(extra: McpExtra | undefined): unknown;
```

The MCP SDK catches whatever a tool handler throws and turns it into an `isError` tool result, so `await next()` resolves normally and the middleware never sees the failure. `getToolError` returns the error the tool handler threw during the current request, with its stack and `cause` intact. It lives on `extra`, which is never serialized to the client.

```ts theme={null}
server.mcpMiddleware("tools/call", async (request, extra, next) => {
  const result = await next();
  const error = getToolError(extra);
  if (error) {
    Sentry.captureException(error);
  }
  return result;
});
```

A tool failure is a valid MCP response, so [`useOnError`](https://docs.skybridge.tech/api-reference/skybridge#useonerror) never runs for it: report tool errors from `mcpMiddleware`, and keep `useOnError` for transport-level failures. Errors raised by the SDK itself (unknown tool, input or output schema validation) never reach your handler and are not reported here. Requests that the SDK rejects before any tool runs, and failures to build the per-request server, go to [`onMcpError`](https://docs.skybridge.tech/api-reference/skybridge#onmcperror) when you set it, and to `console.error` otherwise.

> [card] [Skybridge](https://docs.skybridge.tech/api-reference/skybridge.md)
>
> Configure and run the app that builds this server

> [card] [registerTool](https://docs.skybridge.tech/api-reference/register-tool.md)
>
> Define the tools and views the server exposes

> [card] [generateHelpers](https://docs.skybridge.tech/api-reference/generate-helpers.md)
>
> Turn `AppType` into typed client hooks


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