Skip to content
opentel-mcp

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, 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

    Install opentel-mcp, wrap an MCP server with instrumentMcpServer(), and see your first OpenTelemetry trace — real, tested quickstart code.

Concepts

  • Silent Failures

    MCP tool calls can return isError: true inside a successful JSON-RPC 2.0 response. Why OpenTelemetry misses that, and how opentel-mcp catches it.

  • Deep Failure Fingerprinting

    How opentel-mcp v0.4.0 groups identical failures with a SHA-256-based, 16-hex-char fingerprint, and why it's structurally cardinality-safe.

Reference

  • Metrics

    The four mcp.tool.* OpenTelemetry metrics opentel-mcp emits — calls, errors, silent_failures, and duration — with SigNoz and Prometheus query examples.

  • API Reference

    Exported functions, types, and options in opentel-mcp v0.4.0: instrumentMcpServer, computeFingerprint, toSpanAttributes, 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.