Skybridge

Skybridge is the root of your app: one config object that names your server, wires OAuth, and registers your tools through a handler. It runs an Express-backed HTTP server that serves MCP at /mcp, and you export its type for generateHelpers.

Example

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

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

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 import the app without starting a server.

Constructor

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.

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;
  };

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

`handler`

Receives a fresh McpServer 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, 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.

src/server.ts

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 (oauth: workosProvider({ ... })), a raw OAuthConfig, 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.

`json`

Options for the express.json() parser Skybridge pre-applies, for example to raise the default 100kb body-size limit.

`skills`

Set to true to serve Agent Skills over MCP from src/skills and declare the io.modelcontextprotocol/skills capability.

Skills over MCP tracks SEP-2640, which is still under review. The feature is experimental and may change with the spec.

Properties

`express`

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

Alpic Cloud routes traffic only to /mcp. Custom routes work locally and on self-hosted deployments.

Methods

Every method returns the app, so calls chain.

`use`

app.use(...handlers: RequestHandler[]): this;
app.use(path: string, ...handlers: RequestHandler[]): this;

Registers Express middleware on the underlying app, optionally scoped to a path. Mirrors app.use.

`useOnError`

app.useOnError(...handlers: ErrorRequestHandler[]): this;
app.useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;

Registers an Express error handler, optionally path-scoped, to run after the /mcp route. A default handler runs last, responding with a 500 JSON-RPC error when nothing else has sent a response.

`run`

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 for the per-platform setup.

`connect`

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.

McpServer

The server your handler registers tools on

registerTool

Define the tools and views the app exposes

generateHelpers

Turn AppType into typed client hooks

Server

Auth

Identity Providers

Hooks

Utilities

Types

Low-level

Example

Constructor

`name`, `version`

`handler`

`setup`

`oauth`

`json`

`skills`

Properties

`express`

Methods

`use`

`useOnError`

`run`

`connect`

McpServer

registerTool

generateHelpers

​Example

​Constructor

​name, version

​handler

​setup

​oauth

​json

​skills

​Properties

​express

​Methods

​use

​useOnError

​run

​connect

McpServer

registerTool

generateHelpers

Example

Constructor

`name`, `version`

`handler`

`setup`

`oauth`

`json`

`skills`

Properties

`express`

Methods

`use`

`useOnError`

`run`

`connect`