API Reference

opentel-mcp's package root exports one function for instrumentation (instrumentMcpServer) and a small set of functions and types for Deep Failure Fingerprinting (computeFingerprint, toSpanAttributes, ATTRIBUTE_KEYS, METRIC_SAFE_ATTRIBUTES, DEFAULT_CLASSIFIERS). Every signature below is copied from the package's own src/index.d.ts and the modules it re-exports from, not reconstructed from behavior.

What does instrumentMcpServer() accept?

function instrumentMcpServer<T extends Server | McpServer | DuckTypedMcpServer>(
  server: T,
  options?: InstrumentOptions,
): T & { shutdown?: () => Promise<void> };

server is either a low-level Server (from @modelcontextprotocol/sdk/server/index.js) or a high-level McpServer (from @modelcontextprotocol/sdk/server/mcp.js). It must be called before any tools/call handler is registered — before server.setRequestHandler(CallToolRequestSchema, ...) on a low-level Server, or before any .tool()/.registerTool() call on an McpServer. Calling it more than once on the same server (or on an McpServer and its inner Server interchangeably) is a no-op after the first call.

Scope: as of v0.4.0, only the tools/call handler (registered via CallToolRequestSchema) is wrapped. Requests for resources/* or prompts/* pass through unwrapped and don't emit spans or metrics.

It returns the same object it was given, so it can be used inline:

const server = instrumentMcpServer(new McpServer({ name: 'my-server', version: '1.0.0' }), {
  serviceName: 'my-mcp-server',
});

InstrumentOptions

interface InstrumentOptions {
  serviceName?: string;
  exporterUrl?: string;
  enabled?: boolean;       // default: true
  enableMetrics?: boolean; // default: true
  setupNodeSdk?: boolean;  // default: false
}

What do I get back from instrumentMcpServer()?

The same object passed in — T, unchanged — plus an optional shutdown(): Promise<void>. shutdown is only attached when setupNodeSdk: true; check for its presence before calling it. It flushes and shuts down the NodeTracerProvider opentel-mcp created, and should run during your process's own shutdown sequence so buffered spans aren't lost.

DuckTypedMcpServer

type DuckTypedMcpServer = {
  server: { setRequestHandler: (...args: any[]) => any };
  tool?: (...args: any[]) => any;
  registerTool?: (...args: any[]) => any;
};

A structural fallback type for McpServer-shaped objects that aren't literally instanceof McpServer — the package's own doc comment explains why: McpServer has private fields, so TypeScript treats assignability to it as effectively nominal, and an McpServer instance from a different resolved copy of @modelcontextprotocol/sdk (a hoisting mismatch in a monorepo, for example) would otherwise fail the type check even though instrumentMcpServer() handles it fine at runtime — it never uses instanceof McpServer internally, only this same duck-typing check.

What's exported for Deep Failure Fingerprinting?

These are re-exported at the package root from src/fingerprint/, so they're available as import { computeFingerprint, ... } from 'opentel-mcp' rather than reaching into a subpath.

function computeFingerprint(
  err: unknown,
  ctx: FingerprintContext,
  opts?: ComputeFingerprintOptions,
): FingerprintResult;

interface FingerprintContext {
  readonly toolName?: string;
  readonly origin: FailureOrigin;
  readonly cwd?: string; // default: process.cwd(), used for path normalization
}
 
interface ComputeFingerprintOptions {
  readonly classifiers?: readonly Classifier[]; // prepended to DEFAULT_CLASSIFIERS
  readonly stackFrames?: number;                // default: 5
}

computeFingerprint() never throws — see Deep Failure Fingerprinting for the fallback behavior and why that matters for something running inline in the instrumentation path.

function toSpanAttributes(result: FingerprintResult): Attributes;

Maps a FingerprintResult onto the five mcp.failure.* span attributes. Returns {} if result is malformed in any way — like computeFingerprint(), this must never throw, since it also runs inline on every failure.

const ATTRIBUTE_KEYS: {
  FINGERPRINT: 'mcp.failure.fingerprint';
  SIGNATURE: 'mcp.failure.signature';
  CATEGORY: 'mcp.failure.category';
  ORIGIN: 'mcp.failure.origin';
  ERROR_CLASS: 'mcp.failure.error_class';
};
 
const METRIC_SAFE_ATTRIBUTES: readonly ['mcp.failure.category', 'mcp.failure.origin'];
 
const DEFAULT_CLASSIFIERS: readonly Classifier[]; // 7 built-in classifiers, in match order

What types does opentel-mcp export?

type FailureCategory =
  | 'validation' | 'timeout' | 'network' | 'auth'
  | 'dependency' | 'serialization' | 'internal' | 'unknown';
 
type FailureOrigin = 'tool_error' | 'thrown' | 'transport';
 
interface FingerprintResult {
  readonly fingerprint: string; // 16 lowercase hex chars
  readonly signature: string;   // "<errorClass>@<fn>:<line>", ≤60 chars
  readonly category: FailureCategory;
  readonly origin: FailureOrigin;
  readonly inputs: FingerprintInputs;
}
 
interface FingerprintInputs {
  readonly errorClass: string;
  readonly category: FailureCategory;
  readonly origin: FailureOrigin;
  readonly toolName: string | null; // set only for origin: 'tool_error'
  readonly normalizedMessage: string;
  readonly stackSignature: string;
}

Where do I go from here?

• Deep Failure Fingerprinting — what these fingerprinting exports are for and how the hashing pipeline works.
• Metrics — the four mcp.tool.* instruments instrumentMcpServer() records.
• Silent Failures — the isError detection this whole package exists for.