How to trace MCP requests with OpenTelemetry

// Minimal W3C Trace Context helpers (https://www.w3.org/TR/trace-context/).
// The 2026-07-28 MCP spec (SEP-414) propagates OpenTelemetry context through the
// `_meta` keys `traceparent`, `tracestate`, and `baggage` on every request and
// result, using the same W3C wire format your HTTP stack already speaks.
import { randomBytes } from "node:crypto";

const hex = (n) => randomBytes(n).toString("hex");
export const newTraceId = () => hex(16); // 16 bytes -> 32 hex chars
export const newSpanId = () => hex(8); //  8 bytes -> 16 hex chars

// "00-<32-hex trace-id>-<16-hex span-id>-<2-hex flags>"
export function formatTraceparent({ traceId, spanId, sampled = true }) {
  return `00-${traceId}-${spanId}-${sampled ? "01" : "00"}`;
}

export function parseTraceparent(value) {
  if (typeof value !== "string") return null;
  const m = /^00-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(value);
  if (!m) return null;
  return { traceId: m[1], parentSpanId: m[2], sampled: (parseInt(m[3], 16) & 1) === 1 };
}

// An MCP client that INJECTS its active span context into every request's
// `_meta`, so the server can continue the same trace (2026-07-28 / SEP-414).
import { formatTraceparent, newSpanId } from "./trace.mjs";

export class TracingMcpClient {
  // `span` is the caller's active span: { traceId, spanId }. In real code this
  // comes from your OTel tracer's current context; here it's passed in so the
  // trace is deterministic and testable.
  constructor(endpoint, span, { baggage } = {}) {
    this.endpoint = endpoint;
    this.span = span;
    this.baggage = baggage;
  }

  async _rpc(method, params) {
    // Each outbound call is its own client span, child of the active span,
    // and THAT is what we advertise to the server as the parent.
    const callSpanId = newSpanId();
    const _meta = {
      traceparent: formatTraceparent({ traceId: this.span.traceId, spanId: callSpanId }),
      "io.modelcontextprotocol/clientInfo": { name: "trace-demo-client", version: "1.0.0" },
    };
    if (this.baggage) _meta.baggage = this.baggage;
    const res = await fetch(this.endpoint, {
      method: "POST",
      headers: { "content-type": "application/json", "Mcp-Method": method, "Mcp-Name": params?.name ?? "" },
      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params, _meta }),
    });
    return (await res.json()).result;
  }

  listTools() { return this._rpc("tools/list"); }
  callTool(name, args) { return this._rpc("tools/call", { name, arguments: args }); }
}

// A stateless MCP server over Streamable HTTP that CONTINUES the caller's trace.
// It reads W3C trace context from each request's `_meta` (2026-07-28 / SEP-414),
// opens a child span under the client's span, and stamps its own serverInfo. No
// SDK needed: the released @modelcontextprotocol/sdk (1.30.0) tops out at
// protocol 2025-11-25 and doesn't wire `_meta` trace context yet, so we do it
// at the transport boundary.
import { createServer } from "node:http";
import { parseTraceparent, newSpanId } from "./trace.mjs";

// A stand-in for your real tracer (OTel SDK, Honeycomb, Jaeger, etc.). We just
// record spans in memory so the demo can assert the trace is connected.
export const recordedSpans = [];

function startServerSpan(name, meta) {
  const ctx = parseTraceparent(meta?.traceparent);
  const span = {
    name,
    traceId: ctx?.traceId ?? "orphan", // same trace as the client, or a new root
    spanId: newSpanId(),
    parentSpanId: ctx?.parentSpanId ?? null, // link to the client's span
    baggage: meta?.baggage ?? null, // e.g. "tenant=acme"
  };
  recordedSpans.push(span);
  return span;
}

function handle(msg) {
  const { id, method, params, _meta } = msg;
  const span = startServerSpan(`mcp.server ${method}`, _meta);
  let result;
  if (method === "tools/call") {
    result = { content: [{ type: "text", text: `handled ${params?.name}` }] };
  } else {
    result = { tools: [{ name: "ping" }] };
  }
  return {
    jsonrpc: "2.0",
    id,
    result: {
      ...result,
      resultType: "complete",
      // Echo trace context back so the client can link the response too.
      _meta: {
        "io.modelcontextprotocol/serverInfo": { name: "trace-demo", version: "1.0.0" },
        traceparent: `00-${span.traceId}-${span.spanId}-01`,
      },
    },
  };
}

export function createMcpServer() {
  return createServer((req, res) => {
    if (req.method !== "POST") return void res.writeHead(405).end();
    let body = "";
    req.on("data", (c) => (body += c));
    req.on("end", () =>
      res
        .writeHead(200, { "content-type": "application/json" })
        .end(JSON.stringify(handle(JSON.parse(body)))),
    );
  });
}

if (import.meta.url === `file://${process.argv[1]}`) {
  createMcpServer().listen(8931, () => console.log("MCP server on :8931"));
}

// Runnable proof: the client's trace flows into the server as ONE connected
// trace (shared traceId, correct parent linkage, baggage carried). Run: `node demo.mjs`
import assert from "node:assert/strict";
import { createMcpServer, recordedSpans } from "./server.mjs";
import { TracingMcpClient } from "./client.mjs";
import { newTraceId, newSpanId, parseTraceparent } from "./trace.mjs";

const server = createMcpServer();
await new Promise((r) => server.listen(0, r));
const url = `http://127.0.0.1:${server.address().port}`;

// A request comes in with an active trace (e.g. from the user-facing app).
const rootSpan = { traceId: newTraceId(), spanId: newSpanId() };
const client = new TracingMcpClient(url, rootSpan, { baggage: "tenant=acme" });

const r1 = await client.listTools();
const r2 = await client.callTool("get_forecast", { city: "Lisbon" });

// 1) Both server spans joined the SAME trace as the client - no orphans.
assert.equal(recordedSpans.length, 2);
for (const s of recordedSpans) assert.equal(s.traceId, rootSpan.traceId, "server span shares client traceId");

// 2) Each server span is a CHILD of the client call span (parent linkage set).
for (const s of recordedSpans) assert.match(s.parentSpanId, /^[0-9a-f]{16}$/);

// 3) Baggage (tenant=acme) rode along to the server.
for (const s of recordedSpans) assert.equal(s.baggage, "tenant=acme");

// 4) The server echoed trace context back on the result, still the same trace.
assert.equal(parseTraceparent(r1._meta.traceparent).traceId, rootSpan.traceId);
assert.equal(parseTraceparent(r2._meta.traceparent).traceId, rootSpan.traceId);

server.close();
console.log(`PASS - 1 trace ${rootSpan.traceId} spans client + ${recordedSpans.length} server spans; baggage carried; response context linked.`);

node demo.mjs

PASS - 1 trace 4eac8719ec3d713f522393de1d011407 spans client + 2 server spans; baggage carried; response context linked.