Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-staging.skybridge.tech/llms.txt

Use this file to discover all available pages before exploring further.

The main class for building MCP servers with Skybridge.

​
Import

import { McpServer } from "skybridge/server";

​
Constructor

const server = new McpServer(
  serverInfo: { name: string; version: string },
  options: McpServerOptions
);

​
Parameters

ParameterTypeDescription
serverInfo.namestringName of your MCP server
serverInfo.versionstringVersion of your server
optionsMcpServerOptionsConfiguration options

​
Options

type McpServerOptions = {
  // Additional options as needed
};

​
Methods

​
registerTool

Register a tool. Provide view to bind the tool to a view. See registerTool for the full API. 
server.registerTool(config, handler);

​
use

Register Express middleware on the underlying HTTP server. Supports optional path filtering. 
// Global middleware
server.use(cors());

// Path-scoped middleware
server.use("/api", authMiddleware);

​
useOnError

Register Express error handler on the underlying HTTP server. Supports optional path filtering. 
// Global error handler
server.useOnError((err, req, res, next) => {
  console.error(err);
  res.status(500).send('Something broke!');
})

// Path-scoped error handler
server.useOnError('/api', (err, req, res, next) => {
  console.error(err);
  res.status(500).send('Something broke!');
})
There is a default error handler already registered, defined as: 
function defaultErrorHandler(
  err: unknown,
  _req: express.Request,
  res: express.Response,
  _next: express.NextFunction,
) {
  console.error("Error handling MCP request:", err);
  if (!res.headersSent) {
    res.status(500).json({
      jsonrpc: "2.0",
      error: { code: -32603, message: "Internal server error" },
      id: null,
    });
  }
}

​
mcpMiddleware

Register MCP protocol-level middleware using an onion model. Middleware wraps request/notification handlers and can inspect, modify, or short-circuit them. Must be registered before calling server.run() or server.connect(). 
server.mcpMiddleware(handler);
server.mcpMiddleware(filter, handler);

​
Parameters

ParameterTypeDescription
filterMcpMiddlewareFilterOptional. Determines which methods the middleware applies to. Omit for catch-all.
handlerMcpMiddlewareFnThe middleware function. Call next() to continue the chain.

​
Filter patterns

PatternExampleMatches
Exact method"tools/call"Only tools/call
Wildcard"tools/*"Any method starting with tools/
Category"request"All requests (with extra context)
Category"notification"All notifications (extra is undefined)
Array["tools/call", "resources/read"]Multiple patterns (OR logic)

​
Middleware signature

type McpMiddlewareFn = (
  request: { method: string; params: Record<string, unknown> },
  extra: McpExtra | undefined,
  next: () => Promise<unknown>,
) => Promise<unknown> | unknown;
  • request — the incoming MCP request with method and params
  • extra — SDK context (McpExtra) for requests, undefined for notifications
  • next() — invoke the next middleware or original handler. Can only be called once per middleware.

​
Type-safe filters

When using an exact method string, both params and extra are narrowed automatically: 
server.mcpMiddleware("tools/call", (request, extra, next) => {
  // request.params is typed as CallToolRequest["params"]
  // extra is typed as McpExtra (not undefined)
  console.log(`Tool called: ${request.params.name}`);
  return next();
});

​
Examples

Logging all requests: 
server.mcpMiddleware("request", (request, extra, next) => {
  console.log(`[MCP] ${request.method}`, request.params);
  return next();
});
Auth guard on tool calls: 
server.mcpMiddleware("tools/call", async (request, extra, next) => {
  const token = extra.requestInfo?.headers?.["authorization"];
  if (!token) {
    throw new Error("Unauthorized");
  }
  return next();
});
Modifying params: 
server.mcpMiddleware("tools/call", (request, extra, next) => {
  request.params = { ...request.params, injectedAt: Date.now() };
  return next();
});
Multiple middleware (onion order): 
const server = new McpServer({ name: "my-app", version: "1.0" }, {})
  .mcpMiddleware((request, extra, next) => {
    console.log("outer: before");
    const result = await next();
    console.log("outer: after");
    return result;
  })
  .mcpMiddleware((request, extra, next) => {
    console.log("inner: before");
    return next();
  });
// Logs: outer: before → inner: before → handler → outer: after

​
Type Export Pattern

Export the server type for client-side type inference: 
const server = new McpServer({ name: "my-app", version: "1.0" }, {})
  .registerTool(
    {
      name: "search",
      inputSchema: { query: z.string() },
      view: { component: "search" },
    },
    async ({ query }) => {
      return { structuredContent: { results: [] } };
    },
  );

// Export for generateHelpers
export type AppType = typeof server;

​
Exported Types

The following middleware types are available from skybridge/server: 
import type {
  McpExtra,
  McpMiddlewareFn,
  McpMiddlewareFilter,
  McpTypedMiddlewareFn,
  McpMethodString,
} from "skybridge/server";