Q: Does opentel-mcp add high-cardinality labels to my metrics?

No. A frozen METRIC_SAFE_ATTRIBUTES array — containing only mcp.failure.category (8 values) and mcp.failure.origin (3 values), 24 combinations maximum — is the only path by which a fingerprint-derived value can reach a metric label. The unbounded ones ( fingerprint , signature , error_class ) are structurally confined to span attributes; there's no code path that attaches them to a counter or histogram.

Q: What Node.js versions are supported?

Node.js 20 and newer, per the package's engines field.

Q: How do I export metrics to Prometheus?

Register @opentelemetry/exporter-prometheus (or any Prometheus-compatible exporter) as your MeterProvider 's reader — nothing about instrumentMcpServer() changes. See Metrics for a wiring example and PromQL query.

Question 1

What is opentel-mcp?

Accepted Answer

opentel-mcp is a Node.js OpenTelemetry instrumentation library for Model Context Protocol (MCP) servers. Calling instrumentMcpServer(server, options) wraps a server's tools/call handler and creates an OpenTelemetry span for every tool call, detecting silent failures — CallToolResult.isError: true inside an otherwise-successful JSON-RPC 2.0 response — along the way.

Question 2

What is a silent failure in an MCP server?

Accepted Answer

A silent failure is when an MCP tool call returns a successful JSON-RPC 2.0 response, but the tool result itself carries isError: true. Instrumentation that only checks whether the JSON-RPC call succeeded misses this, since the failure is nested inside a successful response, not reported as a JSON-RPC-level error. See Silent Failures for the full explanation.

Question 3

How does opentel-mcp differ from the standard OpenTelemetry Node.js SDK?

Accepted Answer

The standard OpenTelemetry Node.js SDK has no concept of the MCP protocol and no way to see inside a CallToolResult payload — that's true by definition, since it's a general-purpose SDK, not MCP-aware. opentel-mcp adds MCP-specific instrumentation on top of it, including detecting isError: true inside successful responses and marking the span ERROR.

Question 4

Does opentel-mcp work with fastmcp?

Accepted Answer

No — fastmcp (PrefectHQ/fastmcp) is a Python framework, and opentel-mcp is a Node.js package that instruments servers built on @modelcontextprotocol/sdk, the JavaScript/TypeScript MCP SDK. It can't instrument a Python server directly. The connection between the two projects is narrower: while working on MCP observability, the author found and reported a silent-failure-propagation bug in fastmcp itself (PrefectHQ/fastmcp#4549, fixed in PR #4587) — that's an upstream contribution, not a compatibility claim.

Question 5

What is Deep Failure Fingerprinting?

Accepted Answer

Shipped in v0.4.0, Deep Failure Fingerprinting computes a stable 16-character identifier (SHA-256, truncated) for every thrown error and every isError: true result, so repeated occurrences of the same underlying bug group under one fingerprint instead of showing up as unrelated errors. See Deep Failure Fingerprinting.

Question 6

Does opentel-mcp add high-cardinality labels to my metrics?

Accepted Answer

No. A frozen METRIC_SAFE_ATTRIBUTES array — containing only mcp.failure.category (8 values) and mcp.failure.origin (3 values), 24 combinations maximum — is the only path by which a fingerprint-derived value can reach a metric label. The unbounded ones (fingerprint, signature, error_class) are structurally confined to span attributes; there's no code path that attaches them to a counter or histogram.

Question 7

Can opentel-mcp cause my server to crash?

Accepted Answer

No code path in opentel-mcp is designed to throw into your application. computeFingerprint() in particular runs inside its own top-level try/catch and falls back to a fixed identity (0000000000000000) rather than raising an exception if anything about the fingerprinting pipeline fails.

Question 8

What Node.js versions are supported?

Accepted Answer

Node.js 20 and newer, per the package's engines field.

Question 9

Does opentel-mcp work with SigNoz, Jaeger, Honeycomb, and Grafana Tempo?

Accepted Answer

Yes. opentel-mcp emits standard OpenTelemetry spans and metrics through @opentelemetry/api, so it works with any OTLP-compatible backend — that includes SigNoz, Jaeger, Honeycomb, and Grafana Tempo, along with any other backend that speaks the OpenTelemetry protocol.

Question 10

How do I export metrics to Prometheus?

Accepted Answer

Register @opentelemetry/exporter-prometheus (or any Prometheus-compatible exporter) as your MeterProvider's reader — nothing about instrumentMcpServer() changes. See Metrics for a wiring example and PromQL query.

Question 11

Does opentel-mcp instrument resources and prompts, or just tools?

Accepted Answer

Just tools, as of v0.4.0 — specifically the tools/call request handler. instrumentMcpServer() only wraps the handler registered for CallToolRequestSchema; requests for resources/* or prompts/* pass through unwrapped.

Question 12

Does opentel-mcp support the low-level Server API, or only McpServer?

Accepted Answer

Both. instrumentMcpServer() accepts a low-level Server (from @modelcontextprotocol/sdk/server/index.js) or a high-level McpServer (from @modelcontextprotocol/sdk/server/mcp.js) and detects which one it was given. See API Reference.

Question 13

What happens if I call instrumentMcpServer() more than once on the same server?

Accepted Answer

Nothing extra — it's idempotent. The second and subsequent calls are a no-op, whether made on the same object or interchangeably on an McpServer and the inner Server it wraps.

Question 14

What happens if I register a tool handler before calling instrumentMcpServer()?

Accepted Answer

That handler never gets wrapped — it was registered before the trap was set. instrumentMcpServer() must run before any .tool()/.registerTool() call (McpServer) or server.setRequestHandler(CallToolRequestSchema, ...) call (low-level Server); see Getting Started.

Question 15

Do I need to install @opentelemetry/api separately?

Accepted Answer

Yes. @opentelemetry/api is a peer dependency (^1.9.0 or newer) — install it alongside opentel-mcp: npm install opentel-mcp @opentelemetry/api.

Question 16

Does opentel-mcp create a TracerProvider for me?

Accepted Answer

Only if you set setupNodeSdk: true, which is meant for local development — it creates a NodeTracerProvider that prints to stderr. By default (setupNodeSdk: false), opentel-mcp emits spans through whatever TracerProvider your application already registered globally, or drops them silently if none has been registered — it never overrides your own OpenTelemetry setup.

Question 17

Can I disable opentel-mcp entirely without removing the code?

Accepted Answer

Yes — pass { enabled: false } to instrumentMcpServer() and it becomes a complete no-op.

Question 18

Can I disable metrics but keep tracing?

Accepted Answer

Yes — pass { enableMetrics: false }. Tracing is unaffected either way; metrics are already a zero-overhead no-op until your application registers a MeterProvider, so this is for opting out even when one is registered.

Question 19

Can I disable Deep Failure Fingerprinting?

Accepted Answer

Yes — pass { fingerprinting: false }. It's on by default (true).

Question 20

Is opentel-mcp free and open source?

Accepted Answer

Yes, MIT licensed.

Frequently asked questions

Questions