McpServer

McpServer is the root of your app: an Express-backed server whose methods return the server itself, so you chain your tool registrations off it and export the resulting type for generateHelpers.

Example

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

server.ts

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

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:

type SkybridgeServerOptions = {
  json?: JsonOptions;
  oauth?: OAuthConfig;
  skills?: boolean;
};

json tunes the express.json() parser Skybridge pre-applies, for example to raise the default 100kb body-size limit. oauth is an OAuthConfig, usually from customProvider or a branded provider. 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.authInfo?.extra typed, with no declaration of their own. See Type the Claims You Read. skills set to true serves Agent Skills over MCP from src/skills and declares the io.modelcontextprotocol/skills capability. See the Skills guide.

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 server, so calls chain.

`registerTool`

server.registerTool(config, handler): this;

Registers a tool, optionally bound to a view. See registerTool for the full config and handler.

`use`

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

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

`useOnError`

server.useOnError(...handlers: ErrorRequestHandler[]): this;
server.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.

`mcpMiddleware`

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

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

`getToolError`

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.

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

`run`

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

registerTool

Define the tools and views the server exposes

generateHelpers

Turn AppType into typed client hooks

requireBearerAuth

Require or optionally accept a signed-in user

Server

Auth

Identity Providers

Hooks

Utilities

Types

Low-level

Example

Constructor

Properties

`express`

Methods

`registerTool`

`use`

`useOnError`

`mcpMiddleware`

`getToolError`

`run`

registerTool

generateHelpers

requireBearerAuth

​Example

​Constructor

​Properties

​express

​Methods

​registerTool

​use

​useOnError

​mcpMiddleware

​getToolError

​run

registerTool

generateHelpers

requireBearerAuth

Example

Constructor

Properties

`express`

Methods

`registerTool`

`use`

`useOnError`

`mcpMiddleware`

`getToolError`

`run`