Documentation
opentel-mcp is a Node.js 20+ OpenTelemetry instrumentation library for Model Context Protocol (MCP) servers. These pages cover installing it, what CallToolResult.isError detection actually does, the metrics and fingerprinting it emits, the LLM cost and token attribution it adds as of v0.5.0, and how to migrate from raw @opentelemetry/api instrumentation.
Where to start
New to opentel-mcp? Start with Getting Started. Already have manual OpenTelemetry instrumentation on your MCP server? Start with the Migration Guide instead.Introduction
- Getting Started
OpenTelemetry MCP server instrumentation in one function call: install opentel-mcp, wrap your server with instrumentMcpServer(), see your first trace.
Concepts
- Silent Failures
MCP silent failures: CallToolResult.isError=true inside a successful JSON-RPC response, invisible unless span status is checked. opentel-mcp catches it.
- Deep Failure Fingerprinting
MCP error fingerprinting: opentel-mcp groups identical CallToolResult.isError and thrown failures into one SHA-256 ID — cardinality-safe by construction.
- Cost & Token Attribution
Track LLM cost and token usage on MCP tool calls. Auto-detects Anthropic, OpenAI, and Bedrock usage shapes, priced across 5 providers with pluggable overrides.
- Tracker State Under Stateless HTTP
Why opentel-mcp's four in-memory trackers reset on stateless Streamable HTTP, and what instanceKey (v0.9.0) does — and doesn't — fix.
Reference
- Metrics
The six mcp.tool.* OpenTelemetry metrics opentel-mcp emits — calls, errors, silent_failures, duration, tokens.total, and cost.total — with SigNoz and Prometheus query examples.
- API Reference
Exported functions, types, and options in opentel-mcp v0.10.0: instrumentMcpServer, computeFingerprint, calculateCost, and their real signatures.
Guides
- Migration Guide
Migrating an MCP server from raw @opentelemetry/api instrumentation to opentel-mcp — what stays, what gets deleted, before/after code.