opentel-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thirumalaiboobathi B
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# opentel-mcp
+
+> OpenTelemetry instrumentation for Model Context Protocol (MCP) servers.
+> One-line visibility into which tools your AI agent is calling, how
+> long they take, and which ones fail — via standard OTel traces.
+
+[![CI](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/opentel-mcp.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/blob/main/LICENSE)
+
+**Status: pre-release. Not yet published to npm.**
+
+## Why
+
+When Claude Code calls 15 MCP tools across 3 servers, you have zero
+visibility into which was slow, which errored silently, which sequence
+ran. opentel-mcp wraps any MCP server and emits one OTel span per tool
+invocation with rich attributes, using standard OpenTelemetry APIs so
+it plugs into your existing observability stack (Jaeger, Grafana Tempo,
+Honeycomb, Datadog, whatever).
+
+## Quickstart (5-line usage)
+
+Works with either the low-level `Server` API:
+
+```js
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { instrumentMcpServer } from 'opentel-mcp';
+
+const server = new Server({ name: 'my-server', version: '1.0.0' }, {
+  capabilities: { tools: {} }
+});
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  setupNodeSdk: true,  // dev-friendly stderr output; omit in prod
+                        // if you already have OTel configured
+});
+
+// ...register tools as usual...
+server.setRequestHandler(CallToolRequestSchema, async (request) => { /*...*/ });
+```
+
+...or the high-level `McpServer` API most servers actually use:
+
+```js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { instrumentMcpServer } from 'opentel-mcp';
+
+const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+
+instrumentMcpServer(server, {
+  serviceName: 'my-mcp-server',
+  setupNodeSdk: true,
+});
+
+// ...register tools as usual...
+server.tool('my-tool', async (args) => { /*...*/ });
+```
+
+Either way, `instrumentMcpServer()` must run before any tool is
+registered — see "Ordering constraint" below.
+
+## Semantic conventions
+
+opentel-mcp follows the [MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
+published by the OTel GenAI SIG (they moved there from the main
+`semantic-conventions` repo, where the MCP conventions are now marked
+deprecated). **That spec's status is Development, not Stable** — attribute
+names and requirement levels may still change upstream, and this package
+will follow suit when they do. See ADR 004 in `docs/adr/` for the full
+reasoning.
+
+One attribute, `mcp.tool.argument_count`, is **not** part of the spec — it's
+our own addition, documented as such in `src/attributes.js`. It's a
+privacy-preserving alternative to the spec's opt-in
+`gen_ai.tool.call.arguments`: it gives shape/anomaly signal (argument count
+changed) without capturing any argument values.
+
+## Span attributes emitted
+
+Span (server-side `tools/call` handling) follows the spec's MCP server
+span: name `{mcp.method.name} {tool name}` (e.g. `tools/call echo`, falling
+back to just `mcp.method.name` when no tool name is available), kind
+`SERVER`, status `ERROR` whenever `error.type` is set.
+
+| Attribute | Requirement Level | Description | Example |
+|---|---|---|---|
+| mcp.method.name | Required | JSON-RPC method name | "tools/call" |
+| gen_ai.tool.name | Conditionally Required | Tool name from request | "echo" |
+| gen_ai.operation.name | Recommended | GenAI operation type | "execute_tool" |
+| jsonrpc.request.id | Conditionally Required | JSON-RPC request id (string) | "abc-123" |
+| error.type | Conditionally Required (on failure) | Error class name, or `"tool_error"` when the tool call itself returned `isError: true` | "TypeError" |
+| mcp.tool.argument_count | **Custom — not spec** | Number of arguments (values not captured) | 2 |
+
+Span status description carries the error message on failure (thrown
+errors); no separate error-message attribute is emitted — the spec
+expresses success/failure through span status, not a status attribute.
+
+## Two modes
+
+**One-line (dev):** `setupNodeSdk: true` sets up a NodeTracerProvider
+that prints spans to stderr (safe alongside stdio-transport MCP servers —
+see ADR 003), optionally + an OTLP exporter if `exporterUrl` is provided.
+No separate OTel SDK setup needed — `serviceName` is still required.
+
+**Bring-your-own-SDK (prod):** Omit `setupNodeSdk` (default false).
+opentel-mcp uses whatever tracer provider you've already registered
+via `trace.setGlobalTracerProvider()`. This means it plugs into any
+existing OTel setup without conflict.
+
+## Ordering constraint
+
+Call `instrumentMcpServer()` BEFORE registering any tool handlers —
+before `server.setRequestHandler(CallToolRequestSchema, ...)` (low-level
+`Server`) or before any `.tool()`/`.registerTool()` call (`McpServer`).
+See ADR 002 in docs/adr/ for why.
+
+## Compatibility
+
+- Node.js 20+
+- Windows, macOS, Linux (CI matrix tested)
+- Pure JavaScript, zero native dependencies
+- Supports both low-level `Server` and high-level `McpServer` APIs
+- @modelcontextprotocol/sdk ^1.0.0
+- @opentelemetry/api ^1.9.0
+
+## Roadmap
+
+- v0.2: OTel metrics (`mcp.server.operation.duration`,
+  `mcp.server.session.duration`) alongside traces, plus opt-in
+  `gen_ai.tool.call.arguments` support with a redaction callback
+- v0.3: W3C trace context propagation via `params._meta` per
+  [SEP-414](https://modelcontextprotocol.io/community/seps/414-request-meta),
+  plus client-side instrumentation, so a single trace can span the client
+  call and the server's tool execution
+
+## Contributing
+
+See CONTRIBUTING.md and docs/adr/ for architecture decisions.
+Issues and PRs welcome.
+
+## License
+
+MIT © Thirumalaiboobathi B

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "opentel-mcp",
+  "version": "0.1.0",
+  "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "workspaces": [
+    "examples/hello-server",
+    "examples/hello-mcpserver"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "opentelemetry",
+    "otel",
+    "observability",
+    "tracing",
+    "ai-agents",
+    "claude"
+  ],
+  "author": "Thirumalaiboobathi B",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Thirumalaiboobathi/opentel-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Thirumalaiboobathi/opentel-mcp/issues"
+  },
+  "homepage": "https://github.com/Thirumalaiboobathi/opentel-mcp#readme",
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0",
+    "@opentelemetry/api": "^1.9.0"
+  },
+  "dependencies": {
+    "@opentelemetry/sdk-trace-node": "^2.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
+    "@opentelemetry/resources": "^2.9.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.9.0"
+  }
+}

package/src/attributes.js

@@ -0,0 +1,65 @@
+/**
+ * @module attributes
+ * Semantic attribute constants for opentel-mcp spans.
+ *
+ * Names follow the MCP semantic conventions published by the OTel GenAI
+ * SIG in open-telemetry/semantic-conventions-genai (the conventions moved
+ * there from the main semantic-conventions repo, where they're now marked
+ * deprecated). That spec's status is Development, not Stable — see ADR 004
+ * for what that means for this package and why we're aligning to it now
+ * anyway.
+ */
+
+// --- Spec attributes (MCP semconv, server span) ---
+
+/** Required. The JSON-RPC method name, e.g. "tools/call". */
+export const ATTR_MCP_METHOD_NAME = 'mcp.method.name';
+
+/** Conditionally Required (when the operation targets a specific tool). */
+export const ATTR_GEN_AI_TOOL_NAME = 'gen_ai.tool.name';
+
+/** Conditionally Required (when the client executes a request with a non-null id). */
+export const ATTR_JSONRPC_REQUEST_ID = 'jsonrpc.request.id';
+
+/**
+ * Conditionally Required iff the operation fails — either a thrown
+ * exception or a successful JSON-RPC response whose CallToolResult carries
+ * isError: true, in which case this is set to ERROR_TYPE_TOOL_ERROR.
+ */
+export const ATTR_ERROR_TYPE = 'error.type';
+
+/**
+ * Recommended. SHOULD be "execute_tool" for tool calls, SHOULD NOT be set
+ * otherwise. Lets consumers treat MCP tool-call spans like other GenAI
+ * tool-call spans.
+ */
+export const ATTR_GEN_AI_OPERATION_NAME = 'gen_ai.operation.name';
+
+/**
+ * Well-known error.type value for a JSON-RPC call that succeeded but whose
+ * CallToolResult has isError: true — a tool-level failure, not a transport
+ * or protocol error.
+ */
+export const ERROR_TYPE_TOOL_ERROR = 'tool_error';
+
+/** Well-known gen_ai.operation.name value for tool execution. */
+export const GEN_AI_OPERATION_NAME_EXECUTE_TOOL = 'execute_tool';
+
+/** Well-known mcp.method.name value for a tools/call request. */
+export const MCP_METHOD_NAME_TOOLS_CALL = 'tools/call';
+
+// --- Custom (non-spec) attributes ---
+
+/**
+ * NOT part of the MCP semantic conventions. Our own addition: a
+ * privacy-preserving alternative to the spec's opt-in
+ * gen_ai.tool.call.arguments attribute (which captures full argument
+ * values and is therefore Opt-In due to sensitivity). Recording just the
+ * count gives shape/anomaly signal (e.g. "this call suddenly has 0 args")
+ * without capturing any argument content. See ADR 004 and the README's
+ * "Semantic conventions" section.
+ */
+export const ATTR_MCP_TOOL_ARGUMENT_COUNT = 'mcp.tool.argument_count';
+
+export const ATTR_MCP_SERVER_NAME = 'mcp.server.name';
+export const ATTR_MCP_SERVER_VERSION = 'mcp.server.version';

package/src/config.js

@@ -0,0 +1,40 @@
+/**
+ * @module config
+ * Options parsing and defaults for instrumentMcpServer().
+ */
+
+/**
+ * @typedef {object} InstrumentOptions
+ * @property {string} serviceName - Required. Identifies this server in emitted telemetry.
+ * @property {string} [exporterUrl] - OTLP/HTTP traces endpoint (e.g. 'http://localhost:4318/v1/traces').
+ *   Only takes effect when `setupNodeSdk` is true.
+ * @property {boolean} [enabled=true] - Set to false to disable instrumentation entirely; instrumentMcpServer()
+ *   becomes a no-op.
+ * @property {boolean} [setupNodeSdk=false] - When true, instrumentMcpServer() creates and registers its own
+ *   NodeTracerProvider (always exporting to stderr — safe alongside stdio-transport MCP servers, see ADR 003;
+ *   additionally to `exporterUrl` via OTLP/HTTP if set). When false (the default), spans are emitted via
+ *   whatever OpenTelemetry TracerProvider the host application
+ *   has already registered globally — or dropped silently if none has been registered. This default keeps
+ *   instrumentMcpServer() from ever overriding a host application's own OpenTelemetry setup.
+ */
+
+/**
+ * Validates and applies defaults to raw instrumentMcpServer() options.
+ *
+ * @param {InstrumentOptions} [options]
+ * @returns {Required<InstrumentOptions>}
+ */
+export function resolveOptions(options) {
+  const opts = options ?? {};
+
+  if (typeof opts.serviceName !== 'string' || opts.serviceName.trim() === '') {
+    throw new Error('opentel-mcp: options.serviceName is required and must be a non-empty string.');
+  }
+
+  return {
+    serviceName: opts.serviceName,
+    exporterUrl: opts.exporterUrl,
+    enabled: opts.enabled ?? true,
+    setupNodeSdk: opts.setupNodeSdk ?? false,
+  };
+}

package/src/exporters/stderr.js

@@ -0,0 +1,40 @@
+/**
+ * @module exporters/stderr
+ * A SpanExporter that prints spans to stderr rather than stdout.
+ *
+ * stdio-transport MCP servers write their JSON-RPC protocol messages to
+ * stdout, so a diagnostic exporter sharing that stream would corrupt the
+ * protocol for a real client (see ADR 003). Modeled on
+ * @opentelemetry/sdk-trace's ConsoleSpanExporter, but writes via
+ * console.error (stderr) instead of console.dir (stdout).
+ */
+
+export class StderrSpanExporter {
+  export(spans, resultCallback) {
+    for (const span of spans) {
+      console.error({
+        resource: { attributes: span.resource.attributes },
+        traceId: span.spanContext().traceId,
+        name: span.name,
+        kind: span.kind,
+        id: span.spanContext().spanId,
+        timestamp: span.startTime,
+        duration: span.duration,
+        attributes: span.attributes,
+        status: span.status,
+        events: span.events,
+      });
+    }
+    // 0 === ExportResultCode.SUCCESS (@opentelemetry/core) — inlined to
+    // avoid adding that package as a dependency for one enum value.
+    resultCallback({ code: 0 });
+  }
+
+  shutdown() {
+    return Promise.resolve();
+  }
+
+  forceFlush() {
+    return Promise.resolve();
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { instrumentMcpServer } from './instrument.js';

package/src/instrument.js

@@ -0,0 +1,262 @@
+/**
+ * @module instrument
+ */
+
+import { createRequire } from 'node:module';
+import { trace, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { NodeTracerProvider, SimpleSpanProcessor, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { resolveOptions } from './config.js';
+import { StderrSpanExporter } from './exporters/stderr.js';
+import {
+  ATTR_MCP_METHOD_NAME,
+  ATTR_GEN_AI_TOOL_NAME,
+  ATTR_GEN_AI_OPERATION_NAME,
+  ATTR_JSONRPC_REQUEST_ID,
+  ATTR_MCP_TOOL_ARGUMENT_COUNT,
+  ATTR_ERROR_TYPE,
+  ERROR_TYPE_TOOL_ERROR,
+  GEN_AI_OPERATION_NAME_EXECUTE_TOOL,
+  MCP_METHOD_NAME_TOOLS_CALL,
+} from './attributes.js';
+
+const require = createRequire(import.meta.url);
+const { version: PACKAGE_VERSION } = require('../package.json');
+
+// Protocol-level JSON-RPC method name. Deliberately hardcoded rather than
+// derived from CallToolRequestSchema's zod internals — see ADR 001. Reused
+// as the mcp.method.name attribute value and span-name prefix (ADR 004).
+const TOOLS_CALL_METHOD = MCP_METHOD_NAME_TOOLS_CALL;
+
+// Symbol.for(): must be visible across duplicate installs of this package
+// (e.g. monorepos with dedup issues), not just within one module instance.
+const kInstrumented = Symbol.for('opentel-mcp/instrumented');
+
+const UNSUPPORTED_INPUT_ERROR =
+  'opentel-mcp: instrumentMcpServer() expects either a low-level Server ' +
+  'instance (from @modelcontextprotocol/sdk/server/index.js) or a ' +
+  'high-level McpServer instance (from @modelcontextprotocol/sdk/server/mcp.js).';
+
+const INSTRUMENT_FIRST_ERROR =
+  'opentel-mcp: instrumentMcpServer() must be called BEFORE registering ' +
+  'tool handlers. Move instrumentMcpServer(server, options) to immediately ' +
+  'after `new Server(...)`, before any ' +
+  'server.setRequestHandler(CallToolRequestSchema, ...) calls (low-level ' +
+  'Server) or .tool()/.registerTool() calls (McpServer).';
+
+/**
+ * Detects whether `input` is a low-level Server or a high-level McpServer,
+ * without importing McpServer directly. Importing it would risk the same
+ * dual-package-hazard class of bug the hello-server example hit (two
+ * independently-installed copies of @modelcontextprotocol/sdk producing
+ * two distinct classes, so `instanceof` silently fails) — duck-typing
+ * sidesteps that and stays tolerant of SDK versions that shuffle McpServer's
+ * internals, since only its public, documented shape is checked: a `.server`
+ * object that itself looks like a low-level Server (has a `setRequestHandler`
+ * function), plus a `.tool` or `.registerTool` function on the outer object.
+ * The low-level Server case still uses `instanceof` since Server is already
+ * imported directly for other purposes (ADR 001).
+ *
+ * @param {unknown} input
+ * @returns {{ server: object, outer?: object } | null}
+ */
+function detectServerKind(input) {
+  if (input instanceof Server) {
+    return { server: input };
+  }
+  if (
+    input &&
+    typeof input === 'object' &&
+    input.server &&
+    typeof input.server.setRequestHandler === 'function' &&
+    (typeof input.tool === 'function' || typeof input.registerTool === 'function')
+  ) {
+    return { server: input.server, outer: input };
+  }
+  return null;
+}
+
+/**
+ * Instruments an MCP server so every tool call emits an OpenTelemetry span.
+ *
+ * Accepts either a low-level Server or a high-level McpServer (see
+ * detectServerKind above); McpServer is unwrapped to its inner Server,
+ * which is what's actually patched. Must be called before any `tools/call`
+ * handler is registered — i.e. before any `server.setRequestHandler(CallToolRequestSchema, ...)`
+ * (low-level) or `.tool()`/`.registerTool()` (McpServer) calls (see ADR 001
+ * and ADR 002 in docs/adr/ for why). Idempotent: calling this more than
+ * once — on the same object, or on the outer McpServer and its inner
+ * Server interchangeably — is a no-op after the first call.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').Server | import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('./config.js').InstrumentOptions} options
+ * @returns {*} The same object that was passed in, for chaining. When
+ *   `options.setupNodeSdk` is true, the inner Server (and, when instrumenting
+ *   an McpServer, the outer object too) gets a `shutdown()` method that
+ *   flushes and shuts down the NodeTracerProvider created for it — call it
+ *   during your process's own shutdown sequence to avoid losing buffered
+ *   spans. When `setupNodeSdk` is false (the default), no `shutdown()` is
+ *   attached; lifecycle of the global provider belongs to whoever
+ *   registered it.
+ */
+export function instrumentMcpServer(input, options) {
+  const detected = detectServerKind(input);
+  if (!detected) {
+    throw new Error(UNSUPPORTED_INPUT_ERROR);
+  }
+
+  const { server, outer } = detected;
+
+  if ((outer && outer[kInstrumented]) || server[kInstrumented]) {
+    // Sync the guard onto both objects in case only one was marked so far
+    // (e.g. the inner Server was instrumented directly once before, and
+    // this call is the first time the outer McpServer wrapping it is seen).
+    server[kInstrumented] = true;
+    if (outer) outer[kInstrumented] = true;
+    return input;
+  }
+
+  const resolved = resolveOptions(options);
+
+  if (!resolved.enabled) {
+    server[kInstrumented] = true;
+    if (outer) outer[kInstrumented] = true;
+    return input;
+  }
+
+  assertInstrumentFirst(server);
+
+  const tracer = setupTracer(server, resolved);
+  if (outer && server.shutdown) {
+    outer.shutdown = server.shutdown;
+  }
+
+  const originalSetRequestHandler = server.setRequestHandler.bind(server);
+  server.setRequestHandler = (schema, handler) => {
+    if (schema === CallToolRequestSchema) {
+      handler = wrapToolCallHandler(handler, tracer);
+    }
+    return originalSetRequestHandler(schema, handler);
+  };
+
+  server[kInstrumented] = true;
+  if (outer) outer[kInstrumented] = true;
+  return input;
+}
+
+/**
+ * Throws INSTRUMENT_FIRST_ERROR if a tools/call handler is already
+ * registered on `server`. Uses the SDK's own public
+ * assertCanSetRequestHandler(method) — the same check McpServer uses
+ * internally — rather than reaching into the private _requestHandlers Map.
+ * Feature-detected so a future SDK version that removes this method
+ * degrades to relying on docs + the idempotency guard alone (see ADR 002).
+ * Works identically whether `server` came from a low-level Server or was
+ * unwrapped from an McpServer, since McpServer's .tool()/.registerTool()
+ * lazily call this same server's setRequestHandler(CallToolRequestSchema)
+ * on first registration.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
+ */
+function assertInstrumentFirst(server) {
+  if (typeof server.assertCanSetRequestHandler !== 'function') {
+    return;
+  }
+  try {
+    server.assertCanSetRequestHandler(TOOLS_CALL_METHOD);
+  } catch {
+    throw new Error(INSTRUMENT_FIRST_ERROR);
+  }
+}
+
+/**
+ * Resolves the Tracer to use for this server, optionally standing up an
+ * owned NodeTracerProvider first.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
+ * @param {Required<import('./config.js').InstrumentOptions>} resolved
+ * @returns {import('@opentelemetry/api').Tracer}
+ */
+function setupTracer(server, resolved) {
+  if (resolved.setupNodeSdk) {
+    // StderrSpanExporter, not ConsoleSpanExporter — stdio-transport MCP
+    // servers write JSON-RPC to stdout, so diagnostic span output must go
+    // to stderr instead or it corrupts the protocol stream. See ADR 003.
+    const spanProcessors = [new SimpleSpanProcessor(new StderrSpanExporter())];
+    if (resolved.exporterUrl) {
+      spanProcessors.push(new BatchSpanProcessor(new OTLPTraceExporter({ url: resolved.exporterUrl })));
+    }
+
+    const provider = new NodeTracerProvider({
+      resource: resourceFromAttributes({ 'service.name': resolved.serviceName }),
+      spanProcessors,
+    });
+    provider.register();
+
+    server.shutdown = () => provider.shutdown();
+  }
+
+  // Always the final step: when setupNodeSdk is false, this picks up
+  // whatever TracerProvider the host application has already registered
+  // globally (or the default no-op tracer if none has), rather than
+  // opentel-mcp ever overriding a host's own OpenTelemetry setup.
+  return trace.getTracer('opentel-mcp', PACKAGE_VERSION);
+}
+
+/**
+ * Wraps a tools/call handler in a span covering its execution. This sits as
+ * the innermost layer relative to Server's own request/response validation
+ * wrapping (see ADR 001), so the span times exactly the real handler logic.
+ *
+ * Span shape follows the MCP semantic conventions' server span (ADR 004):
+ * name `{mcp.method.name} {target}` (falling back to just the method name
+ * when no tool name is available), kind SERVER, and status ERROR whenever
+ * error.type is set — which happens either because the handler threw, or
+ * because it resolved successfully but returned a CallToolResult with
+ * isError: true (a JSON-RPC-level success carrying a tool-level failure;
+ * the spec calls this error.type value "tool_error"). In the isError case
+ * the result is returned unchanged and nothing is thrown — the JSON-RPC
+ * call itself succeeded.
+ *
+ * @param {Function} handler
+ * @param {import('@opentelemetry/api').Tracer} tracer
+ */
+function wrapToolCallHandler(handler, tracer) {
+  return (request, extra) => {
+    const toolName = request?.params?.name;
+    const spanName = toolName ? `${TOOLS_CALL_METHOD} ${toolName}` : TOOLS_CALL_METHOD;
+
+    return tracer.startActiveSpan(spanName, { kind: SpanKind.SERVER }, async (span) => {
+      const argumentCount = Object.keys(request?.params?.arguments ?? {}).length;
+
+      span.setAttribute(ATTR_MCP_METHOD_NAME, TOOLS_CALL_METHOD);
+      span.setAttribute(ATTR_GEN_AI_OPERATION_NAME, GEN_AI_OPERATION_NAME_EXECUTE_TOOL);
+      span.setAttribute(ATTR_GEN_AI_TOOL_NAME, toolName);
+      span.setAttribute(ATTR_MCP_TOOL_ARGUMENT_COUNT, argumentCount);
+      if (extra?.requestId !== undefined && extra?.requestId !== null) {
+        span.setAttribute(ATTR_JSONRPC_REQUEST_ID, String(extra.requestId));
+      }
+
+      try {
+        const result = await handler(request, extra);
+        if (result?.isError === true) {
+          span.setAttribute(ATTR_ERROR_TYPE, ERROR_TYPE_TOOL_ERROR);
+          span.setStatus({ code: SpanStatusCode.ERROR });
+        } else {
+          span.setStatus({ code: SpanStatusCode.OK });
+        }
+        return result;
+      } catch (err) {
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+        span.setAttribute(ATTR_ERROR_TYPE, err?.name ?? 'Error');
+        throw err;
+      } finally {
+        span.end();
+      }
+    });
+  };
+}