Embed as a library

@ratel-ai/mcp-server can run inside your process. Use it when you want Ratel Local's upstream aggregation but need to own startup, transport, or shutdown.

This is the inverse of the SDK's registerMcpServer: the SDK ingests an MCP server into a catalog, while this package exposes a catalog as an MCP server. See the ingestion guides for TypeScript or Python.

Install

pnpm add @ratel-ai/mcp-server@0.4.0 @modelcontextprotocol/sdk

The key entry points are summarized in the @ratel-ai/mcp-server package reference.

Build and serve a gateway

buildGatewayFromConfig connects the configured upstreams and builds their catalog. createMcpServer exposes that catalog's capability tools over an MCP transport.

import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  buildGatewayFromConfig,
  createMcpServer,
} from "@ratel-ai/mcp-server";

const gateway = await buildGatewayFromConfig({
  mcpServers: {
    context7: {
      type: "stdio",
      command: "npx",
      args: ["-y", "@upstash/context7-mcp"],
    },
  },
});

const server = await createMcpServer(gateway.catalog, {
  name: "my-gateway",
  version: "0.1.0",
  transport: new StdioServerTransport(),
  skillCatalog: gateway.skillCatalog,
  upstreamServers: gateway.upstreamServers,
  runAuthFlow: gateway.runAuthFlow,
});

gateway.setListChangedNotifier(server.notifyToolListChanged);

const shutdown = async () => {
  try {
    await server.close();
  } finally {
    await gateway.close();
  }
};

process.once("SIGINT", () => void shutdown());
process.once("SIGTERM", () => void shutdown());

The optional server fields mirror the CLI's serve wiring:

• A non-empty skillCatalog registers get_skill_content.
• runAuthFlow registers the auth capability tool.
• upstreamServers lists aggregated upstreams in the server instructions.

buildGatewayFromConfig degrades per upstream: it logs an unsupported transport, connection failure, or authorization requirement and continues building. Supply logger in its options to route those messages into your application's logging.

gateway.upstreamServers contains connected upstreams plus entries marked needsAuth; unsupported and other failed entries are absent. It is not proof that every config entry started.

Keep the tool list current

The server handle exposes notifyToolListChanged(). Call it after a runtime change that alters the capability tools visible to the connected client.

Close both layers

server.close() closes the downstream MCP server and its transport. gateway.close() closes the upstream connections created by buildGatewayFromConfig.

Always close both, and put gateway.close() in a finally block. Closing only the server can leave upstream child processes or network connections running.

Next steps