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

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

`run`

registerTool

generateHelpers

requireBearerAuth

​Example

​Constructor

​Properties

​express

​Methods

​registerTool

​use

​useOnError

​mcpMiddleware

​run

registerTool

generateHelpers

requireBearerAuth

Example

Constructor

Properties

`express`

Methods

`registerTool`

`use`

`useOnError`

`mcpMiddleware`

`run`