ConcurrentMCPServer

The main entry point for the framework. ConcurrentMCPServer handles tool registration, middleware composition, transport selection, and lifecycle management.

Constructor

import { ConcurrentMCPServer } from "@casys/mcp-server";

const server = new ConcurrentMCPServer(options: ConcurrentServerOptions);

ConcurrentServerOptions

interface ConcurrentServerOptions {
  name: string;                          // Server name (shown to clients)
  version: string;                       // Semver version
  maxConcurrent?: number;                // Default: 10
  backpressureStrategy?: "sleep" | "queue" | "reject";  // Default: "sleep"
  backpressureSleepMs?: number;          // Default: 10
  rateLimit?: RateLimitOptions;          // Optional rate limiting
  validateSchema?: boolean;              // Default: false
  enableSampling?: boolean;              // Enable LLM sampling bridge
  samplingClient?: SamplingClient;       // Custom sampling client
  logger?: (msg: string) => void;        // Default: console.error
  auth?: AuthOptions;                    // OAuth2/Bearer config
}

RateLimitOptions

interface RateLimitOptions {
  maxRequests: number;    // Max requests per window
  windowMs: number;       // Window size in milliseconds
}

AuthOptions

interface AuthOptions {
  provider: AuthProvider;   // Use presets (createGoogleAuthProvider, etc.) or JwtAuthProvider
}

Registration methods

All registration must happen before calling start() or startHttp().

registerTool

server.registerTool(tool: MCPTool, handler: ToolHandler): void;

server.registerTool(
  {
    name: "greet",
    description: "Greet someone",
    inputSchema: {
      type: "object",
      properties: { name: { type: "string" } },
      required: ["name"],
    },
    requiredScopes: ["read"],  // Optional — requires this scope if auth is configured
  },
  ({ name }) => `Hello, ${name}!`,
);

registerTools

server.registerTools(tools: MCPTool[], handlers: Map<string, ToolHandler>): void;

Bulk-register tools. Map keys must match tool names exactly.

registerResource

server.registerResource(resource: MCPResource, handler: ResourceHandler): void;

registerResources

server.registerResources(
  resources: MCPResource[],
  handlers: Map<string, ResourceHandler>,
): void;

Bulk-register resources.

use

server.use(middleware: Middleware): this;

Add a custom middleware to the pipeline. Returns this for chaining:

server
  .use(logging)
  .use(metrics)
  .use(caching);

See the Middleware Pipeline guide for patterns and recipes.

Transport methods

start

await server.start(): Promise<void>;

Start with STDIO transport. Use this for local tools (Claude Desktop, Cursor, etc.). Blocks until the server is stopped.

startHttp

await server.startHttp(options: HttpServerOptions): Promise<void>;

Start with Streamable HTTP transport. Includes SSE streaming, session management, and RFC 9728 discovery.

interface HttpServerOptions {
  port: number;
  hostname?: string;  // Default: "0.0.0.0"
}

stop

await server.stop(): Promise<void>;

Graceful shutdown. Waits for in-flight requests to complete before closing.

Monitoring methods

getMetrics

server.getMetrics(): QueueMetrics;
// { inFlight: number, queued: number }

getRateLimitMetrics

server.getRateLimitMetrics(): { keys: number, totalRequests: number } | null;

Returns null if rate limiting is not configured.

getToolCount / getToolNames

server.getToolCount(): number;
server.getToolNames(): string[];

getResourceCount / getResourceUris

server.getResourceCount(): number;
server.getResourceUris(): string[];

SSE methods (HTTP transport only)

sendToSession

server.sendToSession(sessionId: string, message: Record<string, unknown>): void;

Push a message to a specific SSE session.

broadcastNotification

server.broadcastNotification(
  method: string,
  params?: Record<string, unknown>,
): void;

Push a notification to all connected SSE clients.

getSSEClientCount

server.getSSEClientCount(): number;