MCP Server Framework - v1.0.0
    Preparing search index...

    Interface ServerOptions

    Complete server configuration options.

    This interface provides a declarative way to configure an MCP server. All options have sensible defaults.

    const options: ServerOptions = {
      name: 'my-mcp-server',
      version: '1.0.0',
      transport: { mode: 'http', port: 8080 },
      capabilities: { tools: true, resources: true },
      lifecycle: {
        onStarted: () => console.log('Server started!'),
      },
    };
    interface ServerOptions {
        auth?: AuthOptions;
        capabilities?: ServerCapabilities;
        handlers?: HandlersConfig;
        health?: HealthConfig<ServiceClient>;
        lifecycle?: ServerLifecycleHooks;
        name: string;
        onBeforeTelemetryInit?: () => void;
        session?: SessionConfigOptions;
        shutdown?: Partial<ShutdownConfig>;
        telemetryEnabled?: boolean;
        telemetryServiceName?: string;
        transport: TransportOptions;
        version: string;
    }
    Index

    Properties

    auth? capabilities? handlers? health? lifecycle? name onBeforeTelemetryInit? session? shutdown? telemetryEnabled? telemetryServiceName? transport version

    Properties

    auth?: AuthOptions

    Authentication configuration.

    Enables OAuth 2.1 or custom token verification on the server. When configured, the /mcp endpoint requires Bearer authentication. Health and metrics endpoints remain unauthenticated for probes.

    Only relevant for HTTP-based transports — stdio mode does not support authentication (a warning is logged if configured).

    createServer({
      name: 'my-server',
      version: '1.0.0',
      transport: { mode: 'http' },
      auth: {
        provider: myOAuthProvider,
        issuerUrl: new URL('https://auth.example.com'),
        requiredScopes: ['mcp:read'],
      },
    });

    createServer({
      name: 'my-server',
      version: '1.0.0',
      transport: { mode: 'http' },
      auth: {
        provider: { verifyAccessToken: async (token) => ({ ... }) },
      },
    });

    AuthOptions for all configuration options

    capabilities?: ServerCapabilities

    Server capabilities to advertise.

    { tools: { listChanged: true }, logging: true }
    handlers?: HandlersConfig

    Custom protocol handler hooks.

    Allows customizing behavior when MCP protocol events occur. The framework handles protocol compliance - these are for app logic.

    Note: Cancellation is handled automatically by the framework.

    handlers: {
      onPing: () => metrics.increment('mcp.ping'),
    }
    health?: HealthConfig<ServiceClient>

    Health endpoint configuration for API connectivity monitoring.

    Wires a ConnectionStateManager to the /ready endpoint so readiness probes reflect the actual API connection state.

    lifecycle?: ServerLifecycleHooks

    Lifecycle hooks for startup/shutdown.

    name: string

    Server name displayed to MCP clients.

    'my-mcp-server', 'api-mcp-server'
    onBeforeTelemetryInit?: () => void

    Called before the OpenTelemetry SDK is initialized.

    Power users can use this callback to configure low-level OTEL APIs before the framework creates the NodeSDK instance. Common use cases:

    • Set a custom DiagLogger via diag.setLogger() for SDK-level diagnostics (by default no DiagLogger is set — output is suppressed)
    • Register custom instrumentation
    • Configure global propagators or samplers

    The callback runs after framework config resolution but before OTEL_LOG_LEVEL is consumed from process.env and SDK construction. If you set a DiagLogger here, the framework will not override it.

    Important: Custom DiagLoggers must NOT write to stdout (reserved for MCP protocol data in stdio transport mode).

    import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';

    const server = createServer({
      name: 'my-server',
      version: '1.0.0',
      onBeforeTelemetryInit: () => {
        diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG);
      },
    });
    session?: SessionConfigOptions

    Session management configuration.

    Fine-tune session lifecycle behavior (timeouts, cleanup intervals, capacity). Only relevant for HTTP-based transports — stdio always uses a single session with no background tasks.

    All values are optional and fall back to environment variables / config file defaults from the standard config cascade.

    SessionConfigOptions for available options and defaults

    shutdown?: Partial<ShutdownConfig>

    Shutdown configuration.

    telemetryEnabled?: boolean

    Enable OpenTelemetry tracing and metrics.

    When set via createServer(), this is resolved from:

    1. Explicit telemetry option (highest priority)
    2. OTEL_ENABLED env var or config file (fallback)
    undefined (resolved from config)
    telemetryServiceName?: string

    OpenTelemetry service name.

    Server name
    transport: TransportOptions

    Transport configuration (required).

    Explicitly specify how the server communicates with clients. Use { mode: 'stdio' } for CLI usage or { mode: 'http' } for network usage.

    version: string

    Server version (typically from package.json).

    '1.0.0'

    Settings

    Member Visibility

    On This Page

    Properties