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

# Skybridge

> Configure and run your app

`Skybridge` is the root of your app: one config object that names your server, wires OAuth, and registers your [tools](https://docs.skybridge.tech/build/tools.md) through a `handler`. It runs an [Express](https://expressjs.com/)-backed HTTP server that serves MCP at `/mcp`, and you export its type for [`generateHelpers`](https://docs.skybridge.tech/api-reference/generate-helpers).

## Example

The app registers one tool and exports its type for the typed client hooks. A separate entry file runs it.

```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(/* ... */),
});

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

```ts src/index.ts theme={null}
import { app } from "./server.js";

export default await app.run();
```

Keeping the definition in `server.ts` and the `run()` call in `index.ts` lets tests and [evals](https://docs.skybridge.tech/test/evals.md) import the app without starting a server.

## Constructor

```ts theme={null}
new Skybridge(config: SkybridgeConfig);
```

`config` merges the MCP implementation info, the SDK's `ServerOptions`, and Skybridge's own fields. Every type is inferred from it: the config passed to `handler` from `setup`, the auth claims from `oauth`, and the tool registry from what `handler` returns.

```ts theme={null}
type SkybridgeConfig = Implementation &
  ServerOptions & {
    handler: (server: McpServer, config: Config) => McpServer;
    setup?: () => Config | Promise<Config>;
    oauth?: OAuthConfig | OAuthProvider | ((config: Config) => OAuthConfig | OAuthProvider);
    json?: JsonOptions;
    skills?: boolean;
    onMcpError?: (error: Error) => void;
  };
```

### `name`, `version`

The MCP implementation info (`name`, `version`, and optionally `title`, `description`, `icons`, `websiteUrl`). SDK `ServerOptions` such as `instructions` or `capabilities` are forwarded when you set them; registering tools and views advertises those capabilities for you.

`icons` is the app's icon, a standard MCP field. Hosts choose whether and where to show it. Tools can carry their own [`icons`](https://docs.skybridge.tech/api-reference/register-tool#icons) too.

### `handler`

Receives a fresh [`McpServer`](https://docs.skybridge.tech/api-reference/mcp-server) and must **return** the chain of registrations. That return value is what carries your tool types into `typeof app`.

The handler runs for **every request**, so keep it to registration. Anything else in its body (a connection pool, a timer, a file read) runs per request too: move it into [`setup`](#setup), whose result is the handler's second argument. Skybridge warns once in the console when a handler takes more than 50ms. The handler must stay synchronous.

### `setup`

Loads what the app needs before it serves: a connection pool, a client, remote config, secrets. It runs **once**, at `run()` or on the first request, never when the module is imported. Its awaited result is passed to `handler` as the second argument, and to `oauth` when `oauth` is a function.

```ts src/server.ts theme={null}
export const app = new Skybridge({
  name: "shop",
  version: "1.0",
  setup: async () => loadConfig(),
  oauth: (config) => descopeProvider({ url: config.mcpServerUrl }),
  handler: (server, config) => server.registerTool(/* reads config */),
});
```

### `oauth`

An [identity provider](https://docs.skybridge.tech/guides/auth-providers.md) (`oauth: workosProvider({ ... })`), a raw [`OAuthConfig`](https://docs.skybridge.tech/api-reference/custom-provider#returns), or a function of the `setup` result returning either. Providers defer discovery: nothing runs at module import, the network call happens once at `run()`. When set, it mounts the well-known OAuth metadata and bearer-token verification on `/mcp`.

The config also carries the claim shape its verifier produces, so handlers read `extra.http.authInfo.extra` typed, with no declaration of their own. See [Type the Claims You Read](https://docs.skybridge.tech/build/auth.md#type-the-claims-you-read).

### `json`

Options for 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.

### `skills`

Set to `true` to serve [Agent Skills over MCP](https://docs.skybridge.tech/guides/skills.md) from `src/skills` and declare the `io.modelcontextprotocol/skills` capability.

> [!NOTE]
>
> Skills over MCP tracks [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640), which is still under review. The feature is **experimental** and may change with the spec.

### `onMcpError`

Replaces the error reporter of the built-in `/mcp` handler. By default, Skybridge logs each error that the MCP SDK handler reports, except `UnsupportedProtocolVersionError`. The log line is `console.error("Error handling MCP request:", error)`.

When you set `onMcpError`, it receives every error that the MCP SDK handler or its Node adapter reports. This includes:

* Requests the SDK rejects before any tool runs, such as an unsupported protocol version or a malformed header.
* Failures to build or serve the per-request server.

`UnsupportedProtocolVersionError` also reaches your function, because the skip belongs to the default reporter. Filter it yourself if you do not want it.

Node adapter errors, such as a request after the handler is closed, reach only `onMcpError`. The default reporter does not log them.

The option only reports. It does not change the response. It can run before the response is sent, so keep it fast and synchronous. Skybridge does not await a returned promise, so a rejected promise is an unhandled rejection, which ends the process by default in Node. An error that the function throws is dropped.

Other errors go elsewhere:

* Tool errors are valid MCP results. Read them with [`getToolError`](https://docs.skybridge.tech/api-reference/mcp-server#gettoolerror).
* Express errors on `/mcp` go to your [`useOnError`](#useonerror) handlers, then to the default Express handler. That handler also logs them.

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

export const app = new Skybridge({
  name: "shop",
  version: "1.0",
  onMcpError: (error) => {
    const unsupportedVersion =
      error instanceof ProtocolError &&
      error.code === ProtocolErrorCode.UnsupportedProtocolVersion;
    if (!unsupportedVersion) {
      console.warn({ event: "mcp_error", name: error.name });
    }
  },
  handler: (server) => server.registerTool(/* ... */),
});
```

## Properties

### `express`

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

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

## Methods

`use` and `useOnError` return the app, so calls chain.

### `use`

```ts theme={null}
app.use(...handlers: RequestHandler[]): this;
app.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}
app.useOnError(...handlers: ErrorRequestHandler[]): this;
app.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.

### `run`

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

Resolves `setup` and `oauth`, 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](https://docs.skybridge.tech/ship/deploy.md) for the per-platform setup.

### `connect`

```ts theme={null}
app.connect(transport: Transport): Promise<void>;
```

Connects the app to a transport you manage, such as stdio for a desktop host. For HTTP, `run()` sets the transport up for you.

> [card] [McpServer](https://docs.skybridge.tech/api-reference/mcp-server.md)
>
> The server your handler registers tools on

> [card] [registerTool](https://docs.skybridge.tech/api-reference/register-tool.md)
>
> Define the tools and views the app 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.