instrumentServer

Patch an MCP server with OpenTelemetry tracing, metrics, and safety hooks.

function instrumentServer(
  server: McpServer,
  config: TelemetryConfig,
): ObservabilityInstance

Constructs a TelemetryManager, wires up the OpenTelemetry Node SDK, then calls McpServerInstrumentation.instrument() to patch server.registerTool so every subsequent tool registration produces spans and metrics automatically.

Parameters

server · McpServer · required

An instance of McpServer from @modelcontextprotocol/sdk/server/mcp. Must be passed before any tools are registered (instrumentation only applies to tools registered after this call).

config · TelemetryConfig · required

Configuration for the telemetry pipeline. See the TelemetryConfig reference for every field.

Returns

instance · ObservabilityInstance

An object with helpers for custom instrumentation and shutdown:

• startActiveSpan(name, attributes, fn)
• getHistogram(name, options)
• getIncrementCounter(name, options)
• processTelemetryAttributes(data)
• shutdown(): Promise<void>

See ObservabilityInstance.

Example

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { instrumentServer } from '@sedata-ai/mcp'
import type { TelemetryConfig } from '@sedata-ai/mcp'

const server = new McpServer({ name: 'weather-mcp', version: '1.0.0' })

const telemetryConfig: TelemetryConfig = {
  serverName: 'weather-mcp',
  serverVersion: '1.0.0',
  exporterEndpoint: 'https://otel.sedata-ai.tech/v1',
  exporterAuth: {
    type: 'bearer',
    token: process.env.SEDATA_TOKEN!,
  },
  samplingRate: 0.25,
  enableArgumentCollection: false,
}

const telemetry = instrumentServer(server, telemetryConfig)

Side effects

Calling instrumentServer does several things at once:

1. Validates the config via ConfigValidator.validate(config). Throws on invalid input (missing endpoint, bad sampling rate, malformed auth).
2. Stores the API key for the safety-check API. The token from exporterAuth.apiKey or exporterAuth.token is forwarded.
3. Starts the OpenTelemetry Node SDK with trace + metric exporters, sampler, and resource detectors.
4. Patches server.registerTool to wrap every handler in an instrumented function.

When to call it

Always immediately after constructing the McpServer, before any registerTool:

const server = new McpServer({ name: 'X', version: '1.0.0' })
const telemetry = instrumentServer(server, config) // ← here
server.registerTool('my-tool', /* ... */)         // ← instrumented

Tools registered before instrumentServer are not instrumented.

Errors

Error	Cause
exporterEndpoint is required	exporterEndpoint missing and exporterType is not 'console'.
samplingRate must be between 0 and 1	Out-of-range samplingRate.
metricExportIntervalMs must be >0	Non-positive interval.
batchTimeout must be >=0	Non-positive timeout.
Bearer token is required when using bearer auth	exporterAuth.type === 'bearer' with no token.
API key is required when using apiKey auth	exporterAuth.type === 'apiKey' with no apiKey.
Username and password are required when using basic auth	basic auth with missing fields.

All thrown synchronously at the call site.

See also

TelemetryConfig

Every config field with defaults.

ObservabilityInstance

The object returned by this function.