toad-eye 2.6.1 → 2.8.0

package/dist/cli.js

@@ -97,19 +97,26 @@ function down() {
 export function findContainerByService(containers, serviceKey) {
     return containers.find((c) => c.Service === serviceKey);
 }
+function isContainerHealthy(container) {
+    return container?.State === "running" && container.ExitCode === 0;
+}
 function status() {
     const composeFile = requireInfra();
     try {
-        const output = execFileSync("docker", ["compose", "-f", composeFile, "ps", "--format", "json"], { encoding: "utf-8" });
+        const output = execFileSync("docker", ["compose", "-f", composeFile, "ps", "--all", "--format", "json"], { encoding: "utf-8" });
         const lines = output.trim().split("\n").filter(Boolean);
         const containers = lines.map((line) => JSON.parse(line));
         console.log("\u{1f438} toad-eye stack:");
         console.log();
         for (const svc of SERVICES) {
-            const container = findContainerByService(containers, svc.service);
-            const state = container?.State === "running" ? "\u{1f7e2}" : "\u{1f534}";
+            const container = containers.find((c) => c.Service === svc.service);
+            const healthy = isContainerHealthy(container);
+            const icon = healthy ? "\u{1f7e2}" : "\u{1f534}";
+            const suffix = container && !healthy
+                ? ` (${container.State}${container.ExitCode ? `, exit code ${container.ExitCode}` : ""})`
+                : "";
             const loginInfo = "login" in svc ? ` (${svc.login})` : "";
-            console.log(`  ${state} ${svc.name.padEnd(16)} ${svc.url}${loginInfo}`);
+            console.log(`  ${icon} ${svc.name.padEnd(16)} ${svc.url}${loginInfo}${suffix}`);
         }
         console.log();
     }

package/dist/core/tracer.js

@@ -8,6 +8,9 @@ import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { initMetrics, resetMetrics } from "./metrics.js";
 import { resetCustomPricing } from "./pricing.js";
 import { enableAll, disableAll } from "../instrumentations/registry.js";
+import { enableMcpInstrumentation, disableMcpInstrumentation, } from "../instrumentations/mcp.js";
+import { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "../mcp/client.js";
+import { resetMcpMetrics } from "../mcp/metrics.js";
 import { BudgetTracker } from "../budget/index.js";
 import { ToadEyeAISpanProcessor } from "../vercel.js";
 const DEFAULT_ENDPOINT = "http://localhost:4318";
@@ -122,8 +125,22 @@ export function initObservability(config) {
         budgetTracker = new BudgetTracker(config.budgets, config.onBudgetExceeded ?? "warn", config.downgradeCallback);
     }
     if (config.instrument?.length) {
-        // Filter out 'ai' — it uses SpanProcessor, not monkey-patching
-        const patchProviders = config.instrument.filter((i) => i !== "ai");
+        // Handle MCP server auto-instrumentation
+        if (config.instrument.includes("mcp")) {
+            const patched = enableMcpInstrumentation();
+            if (!patched) {
+                console.warn(`toad-eye: "@modelcontextprotocol/sdk" not found — install it to enable MCP server auto-instrumentation`);
+            }
+        }
+        // Handle MCP client auto-instrumentation
+        if (config.instrument.includes("mcp-client")) {
+            const patched = enableMcpClientInstrumentation();
+            if (!patched) {
+                console.warn(`toad-eye: "@modelcontextprotocol/sdk" not found — install it to enable MCP client auto-instrumentation`);
+            }
+        }
+        // Filter out special targets — they use separate mechanisms
+        const patchProviders = config.instrument.filter((i) => i !== "ai" && i !== "mcp" && i !== "mcp-client");
         if (patchProviders.length > 0) {
             // enableAll is async (lazy-loads provider modules on first call).
             // Fire-and-forget: patching completes before any async SDK call.
@@ -137,10 +154,13 @@ export async function shutdown() {
     if (!sdk)
         return;
     disableAll();
+    disableMcpInstrumentation();
+    disableMcpClientInstrumentation();
     await sdk.shutdown();
     sdk = null;
     currentConfig = null;
     budgetTracker = null;
     resetMetrics();
+    resetMcpMetrics();
     resetCustomPricing();
 }

package/dist/instrumentations/mcp.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Auto-instrumentation for MCP SDK.
+ *
+ * Patches McpServer.prototype so that any server instance created after
+ * enableMcpInstrumentation() is automatically instrumented — no need
+ * to call toadEyeMiddleware(server) manually.
+ *
+ * Uses __toad_eye_mcp_patched flag to prevent double-instrumentation
+ * when both auto and manual approaches are used.
+ */
+export declare function enableMcpInstrumentation(): boolean;
+export declare function disableMcpInstrumentation(): void;

package/dist/instrumentations/mcp.js

@@ -0,0 +1,85 @@
+/**
+ * Auto-instrumentation for MCP SDK.
+ *
+ * Patches McpServer.prototype so that any server instance created after
+ * enableMcpInstrumentation() is automatically instrumented — no need
+ * to call toadEyeMiddleware(server) manually.
+ *
+ * Uses __toad_eye_mcp_patched flag to prevent double-instrumentation
+ * when both auto and manual approaches are used.
+ */
+import { createRequire } from "node:module";
+import { toadEyeMiddleware } from "../mcp/middleware.js";
+const require = createRequire(import.meta.url);
+const PATCHED_FLAG = "__toad_eye_mcp_patched";
+const MODULE_NAME = "@modelcontextprotocol/sdk/server/mcp.js";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let mcpServerProto = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let originals = null;
+export function enableMcpInstrumentation() {
+    try {
+        require.resolve(MODULE_NAME);
+    }
+    catch {
+        return false;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const sdk = require(MODULE_NAME);
+    const McpServer = sdk.McpServer ?? sdk.default?.McpServer;
+    if (!McpServer?.prototype)
+        return false;
+    if (McpServer.prototype[PATCHED_FLAG])
+        return true;
+    const proto = McpServer.prototype;
+    mcpServerProto = proto;
+    originals = {
+        tool: proto.tool,
+        resource: proto.resource,
+        prompt: proto.prompt,
+    };
+    // WeakSet tracks which instances have been instrumented
+    const instrumented = new WeakSet();
+    function ensureInstrumented(instance) {
+        if (instrumented.has(instance))
+            return;
+        instrumented.add(instance);
+        // Restore original methods so middleware wraps the real ones
+        instance.tool = originals.tool.bind(instance);
+        if (originals.resource)
+            instance.resource = originals.resource.bind(instance);
+        if (originals.prompt)
+            instance.prompt = originals.prompt.bind(instance);
+        toadEyeMiddleware(instance);
+    }
+    proto.tool = function patchedTool(...args) {
+        ensureInstrumented(this);
+        return this.tool(...args);
+    };
+    if (originals.resource) {
+        proto.resource = function patchedResource(...args) {
+            ensureInstrumented(this);
+            return this.resource(...args);
+        };
+    }
+    if (originals.prompt) {
+        proto.prompt = function patchedPrompt(...args) {
+            ensureInstrumented(this);
+            return this.prompt(...args);
+        };
+    }
+    proto[PATCHED_FLAG] = true;
+    return true;
+}
+export function disableMcpInstrumentation() {
+    if (!mcpServerProto || !originals)
+        return;
+    mcpServerProto.tool = originals.tool;
+    if (originals.resource)
+        mcpServerProto.resource = originals.resource;
+    if (originals.prompt)
+        mcpServerProto.prompt = originals.prompt;
+    delete mcpServerProto[PATCHED_FLAG];
+    mcpServerProto = null;
+    originals = null;
+}

package/dist/mcp/client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * MCP Client instrumentation — patches Client.prototype to create
+ * SpanKind.CLIENT spans for outgoing tool calls, resource reads, and prompt gets.
+ *
+ * Injects W3C traceparent into _meta field so server-side middleware
+ * can link client and server spans into one distributed trace.
+ */
+export declare function enableMcpClientInstrumentation(): boolean;
+export declare function disableMcpClientInstrumentation(): void;

package/dist/mcp/client.js

@@ -0,0 +1,137 @@
+/**
+ * MCP Client instrumentation — patches Client.prototype to create
+ * SpanKind.CLIENT spans for outgoing tool calls, resource reads, and prompt gets.
+ *
+ * Injects W3C traceparent into _meta field so server-side middleware
+ * can link client and server spans into one distributed trace.
+ */
+import { createRequire } from "node:module";
+import { trace, context, propagation, SpanKind } from "@opentelemetry/api";
+import { MCP_METHODS, endSpanSuccess, endSpanError } from "./spans.js";
+const require = createRequire(import.meta.url);
+const TRACER_NAME = "toad-eye-mcp-client";
+const PATCHED_FLAG = "__toad_eye_mcp_client_patched";
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let clientProto = null;
+let originals = null;
+/**
+ * Inject W3C traceparent into MCP _meta field.
+ * This allows server-side middleware to extract parent context.
+ */
+function injectTraceContext(params) {
+    const meta = params._meta ?? {};
+    const carrier = {};
+    propagation.inject(context.active(), carrier);
+    if (carrier["traceparent"]) {
+        return {
+            ...params,
+            _meta: {
+                ...meta,
+                traceparent: carrier["traceparent"],
+                ...(carrier["tracestate"] ? { tracestate: carrier["tracestate"] } : {}),
+            },
+        };
+    }
+    return params;
+}
+export function enableMcpClientInstrumentation() {
+    try {
+        require.resolve("@modelcontextprotocol/sdk/client/index.js");
+    }
+    catch {
+        return false;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const sdk = require("@modelcontextprotocol/sdk/client/index.js");
+    const Client = sdk.Client ?? sdk.default?.Client;
+    if (!Client?.prototype)
+        return false;
+    if (Client.prototype[PATCHED_FLAG])
+        return true;
+    const proto = Client.prototype;
+    clientProto = proto;
+    originals = {
+        callTool: proto.callTool,
+        readResource: proto.readResource,
+        getPrompt: proto.getPrompt,
+    };
+    const tracer = trace.getTracer(TRACER_NAME);
+    // --- Patch callTool ---
+    proto.callTool = async function patchedCallTool(params, ...rest) {
+        const toolName = params.name ?? "unknown";
+        const span = tracer.startSpan(`${MCP_METHODS.TOOLS_CALL} ${toolName}`, {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "gen_ai.operation.name": MCP_METHODS.TOOLS_CALL,
+                "mcp.method.name": MCP_METHODS.TOOLS_CALL,
+                "gen_ai.tool.name": toolName,
+            },
+        });
+        const enrichedParams = injectTraceContext(params);
+        try {
+            const result = await context.with(trace.setSpan(context.active(), span), () => originals.callTool.call(this, enrichedParams, ...rest));
+            endSpanSuccess(span);
+            return result;
+        }
+        catch (error) {
+            endSpanError(span, error);
+            throw error;
+        }
+    };
+    // --- Patch readResource ---
+    proto.readResource = async function patchedReadResource(params, ...rest) {
+        const uri = params.uri ?? "unknown";
+        const span = tracer.startSpan(`${MCP_METHODS.RESOURCES_READ} ${uri}`, {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "gen_ai.operation.name": MCP_METHODS.RESOURCES_READ,
+                "mcp.method.name": MCP_METHODS.RESOURCES_READ,
+                "gen_ai.data_source.id": uri,
+            },
+        });
+        const enrichedParams = injectTraceContext(params);
+        try {
+            const result = await context.with(trace.setSpan(context.active(), span), () => originals.readResource.call(this, enrichedParams, ...rest));
+            endSpanSuccess(span);
+            return result;
+        }
+        catch (error) {
+            endSpanError(span, error);
+            throw error;
+        }
+    };
+    // --- Patch getPrompt ---
+    proto.getPrompt = async function patchedGetPrompt(params, ...rest) {
+        const promptName = params.name ?? "unknown";
+        const span = tracer.startSpan(`${MCP_METHODS.PROMPTS_GET} ${promptName}`, {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "gen_ai.operation.name": MCP_METHODS.PROMPTS_GET,
+                "mcp.method.name": MCP_METHODS.PROMPTS_GET,
+                "gen_ai.prompt.name": promptName,
+            },
+        });
+        const enrichedParams = injectTraceContext(params);
+        try {
+            const result = await context.with(trace.setSpan(context.active(), span), () => originals.getPrompt.call(this, enrichedParams, ...rest));
+            endSpanSuccess(span);
+            return result;
+        }
+        catch (error) {
+            endSpanError(span, error);
+            throw error;
+        }
+    };
+    proto[PATCHED_FLAG] = true;
+    return true;
+}
+export function disableMcpClientInstrumentation() {
+    if (!clientProto || !originals)
+        return;
+    clientProto.callTool = originals.callTool;
+    clientProto.readResource = originals.readResource;
+    clientProto.getPrompt = originals.getPrompt;
+    delete clientProto[PATCHED_FLAG];
+    clientProto = null;
+    originals = null;
+}

package/dist/mcp/index.d.ts

@@ -1,3 +1,5 @@
 export { toadEyeMiddleware, traceSampling } from "./middleware.js";
-export type { TraceSamplingOptions } from "./middleware.js";
-export type { ToadMcpOptions, McpSpanAttributes } from "./types.js";
+export type { TraceSamplingOptions, ToadEyeMiddlewareDispose, } from "./middleware.js";
+export type { ToadMcpOptions } from "./types.js";
+export { MCP_METHODS } from "./spans.js";
+export { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "./client.js";

package/dist/mcp/index.js

@@ -1 +1,3 @@
 export { toadEyeMiddleware, traceSampling } from "./middleware.js";
+export { MCP_METHODS } from "./spans.js";
+export { enableMcpClientInstrumentation, disableMcpClientInstrumentation, } from "./client.js";

package/dist/mcp/metrics.d.ts

@@ -3,9 +3,13 @@
  *
  * Separate from core metrics (core/metrics.ts) — these only exist
  * when MCP middleware is active. Initialized on first middleware call.
+ *
+ * All metrics include `mcp.method.name` dimension per OTel MCP semconv.
  */
-export declare function recordMcpToolCall(toolName: string, durationMs: number, status: "success" | "error"): void;
+export declare function recordMcpToolCall(toolName: string, durationMs: number, status: "success" | "error", sessionId?: string): void;
 export declare function recordMcpToolError(toolName: string, errorType: string): void;
 export declare function recordMcpResourceRead(uri: string): void;
 export declare function recordMcpSessionStart(): void;
 export declare function recordMcpSessionEnd(): void;
+/** Reset MCP metrics state — must be called from shutdown() alongside resetMetrics(). */
+export declare function resetMcpMetrics(): void;

package/dist/mcp/metrics.js

@@ -3,15 +3,19 @@
  *
  * Separate from core metrics (core/metrics.ts) — these only exist
  * when MCP middleware is active. Initialized on first middleware call.
+ *
+ * All metrics include `mcp.method.name` dimension per OTel MCP semconv.
  */
 import { metrics, } from "@opentelemetry/api";
 import { GEN_AI_METRICS } from "../types/metrics.js";
+import { MCP_METHODS } from "./spans.js";
 const METER_NAME = "toad-eye-mcp";
 let toolDuration;
 let toolCalls;
 let toolErrors;
 let resourceReads;
 let sessionActive;
+let toolCallers;
 let initialized = false;
 function ensureInit() {
     if (initialized)
@@ -34,19 +38,42 @@ function ensureInit() {
     sessionActive = meter.createUpDownCounter(GEN_AI_METRICS.MCP_SESSION_ACTIVE, {
         description: "Number of active MCP sessions",
     });
+    toolCallers = meter.createCounter(GEN_AI_METRICS.MCP_TOOL_CALLERS, {
+        description: "MCP tool calls by session — use count(distinct) for unique callers",
+    });
 }
-export function recordMcpToolCall(toolName, durationMs, status) {
+export function recordMcpToolCall(toolName, durationMs, status, sessionId) {
     ensureInit();
-    toolCalls.add(1, { "gen_ai.tool.name": toolName, status });
-    toolDuration.record(durationMs, { "gen_ai.tool.name": toolName });
+    toolCalls.add(1, {
+        "gen_ai.tool.name": toolName,
+        "mcp.method.name": MCP_METHODS.TOOLS_CALL,
+        status,
+    });
+    toolDuration.record(durationMs, {
+        "gen_ai.tool.name": toolName,
+        "mcp.method.name": MCP_METHODS.TOOLS_CALL,
+    });
+    if (sessionId) {
+        toolCallers.add(1, {
+            "gen_ai.tool.name": toolName,
+            "mcp.session.id": sessionId,
+        });
+    }
 }
 export function recordMcpToolError(toolName, errorType) {
     ensureInit();
-    toolErrors.add(1, { "gen_ai.tool.name": toolName, "error.type": errorType });
+    toolErrors.add(1, {
+        "gen_ai.tool.name": toolName,
+        "mcp.method.name": MCP_METHODS.TOOLS_CALL,
+        "error.type": errorType,
+    });
 }
 export function recordMcpResourceRead(uri) {
     ensureInit();
-    resourceReads.add(1, { "gen_ai.data_source.id": uri });
+    resourceReads.add(1, {
+        "gen_ai.data_source.id": uri,
+        "mcp.method.name": MCP_METHODS.RESOURCES_READ,
+    });
 }
 export function recordMcpSessionStart() {
     ensureInit();
@@ -56,3 +83,7 @@ export function recordMcpSessionEnd() {
     ensureInit();
     sessionActive.add(-1);
 }
+/** Reset MCP metrics state — must be called from shutdown() alongside resetMetrics(). */
+export function resetMcpMetrics() {
+    initialized = false;
+}

package/dist/mcp/middleware.d.ts

@@ -9,7 +9,11 @@
  * and strict TypeScript. Wrapping the public API is the stable path.
  */
 import type { ToadMcpOptions } from "./types.js";
-export declare function toadEyeMiddleware(server: any, options?: ToadMcpOptions): void;
+export interface ToadEyeMiddlewareDispose {
+    /** Call when the MCP server is shutting down to decrement the active session counter. */
+    (): void;
+}
+export declare function toadEyeMiddleware(server: any, options?: ToadMcpOptions): ToadEyeMiddlewareDispose;
 /**
  * Trace a sampling/createMessage call (server → client LLM request).
  *
@@ -45,4 +49,10 @@ export interface TraceSamplingOptions {
     readonly serverVersion?: string | undefined;
     /** Parent OTel context. */
     readonly parentContext?: import("@opentelemetry/api").Context | undefined;
+    /** MCP session ID. */
+    readonly sessionId?: string | undefined;
+    /** MCP protocol version. */
+    readonly protocolVersion?: string | undefined;
+    /** Network transport: "pipe" (stdio) or "tcp" (HTTP). */
+    readonly networkTransport?: string | undefined;
 }

package/dist/mcp/middleware.js

@@ -8,11 +8,26 @@
  * Why not monkey-patching: MCP SDK uses private class members (_requestHandlers)
  * and strict TypeScript. Wrapping the public API is the stable path.
  */
-import { context, diag, DiagConsoleLogger, DiagLogLevel, } from "@opentelemetry/api";
+import { context, trace, diag, DiagConsoleLogger, DiagLogLevel, } from "@opentelemetry/api";
+import { randomUUID } from "node:crypto";
 import { extractContextFromMeta } from "./context.js";
 import { startToolSpan, startResourceSpan, startPromptSpan, startSamplingSpan, endSpanSuccess, endSpanError, } from "./spans.js";
-import { recordMcpToolCall, recordMcpToolError, recordMcpResourceRead, recordMcpSessionStart, } from "./metrics.js";
+import { recordMcpToolCall, recordMcpToolError, recordMcpResourceRead, recordMcpSessionStart, recordMcpSessionEnd, } from "./metrics.js";
 const DEFAULT_MAX_PAYLOAD_SIZE = 4096;
+/** Detect MCP transport type from server internals. */
+function detectTransport(server) {
+    // Check if server has a transport reference
+    const transport = server.transport ?? server._transport;
+    if (transport && typeof transport === "object") {
+        const name = transport.constructor?.name ?? "";
+        if (/stdio/i.test(name))
+            return "pipe";
+        if (/sse|http/i.test(name))
+            return "tcp";
+    }
+    // Default: stdio is most common for local dev
+    return "pipe";
+}
 function truncate(value, maxBytes) {
     if (value.length <= maxBytes)
         return value;
@@ -23,7 +38,15 @@ function redactObject(obj, keys) {
         return {};
     const result = {};
     for (const [k, v] of Object.entries(obj)) {
-        result[k] = keys.includes(k) ? "[REDACTED]" : v;
+        if (keys.includes(k)) {
+            result[k] = "[REDACTED]";
+        }
+        else if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+            result[k] = redactObject(v, keys);
+        }
+        else {
+            result[k] = v;
+        }
     }
     return result;
 }
@@ -75,7 +98,19 @@ server, options = {}) {
     const redactKeys = options.redactKeys ?? [];
     const maxPayload = options.maxPayloadSize ?? DEFAULT_MAX_PAYLOAD_SIZE;
     const propagate = options.propagateContext ?? true;
-    const spanOpts = { serverName, serverVersion };
+    // Session ID: explicit > server-provided > generated
+    const sessionId = options.sessionId ?? server.sessionId ?? randomUUID().slice(0, 8);
+    // Protocol version from server capabilities or default
+    const protocolVersion = server.protocolVersion ?? server._protocolVersion ?? "2025-03-26";
+    // Detect transport type: pipe (stdio) vs tcp (HTTP)
+    const networkTransport = detectTransport(server);
+    const spanOpts = {
+        serverName,
+        serverVersion,
+        sessionId,
+        protocolVersion,
+        networkTransport,
+    };
     // --- Wrap .tool() ---
     const originalTool = server.tool.bind(server);
     server.tool = function wrappedTool(name, ...rest) {
@@ -110,7 +145,7 @@ server, options = {}) {
             }
             const start = performance.now();
             try {
-                const result = await context.with(context.active(), () => originalHandler(...handlerArgs));
+                const result = await context.with(trace.setSpan(parentCtx, span), () => originalHandler(...handlerArgs));
                 const durationMs = performance.now() - start;
                 // Record outputs if enabled
                 if (recordOutputs && result) {
@@ -118,14 +153,14 @@ server, options = {}) {
                     span.setAttribute("gen_ai.tool.call.result", serialized);
                 }
                 endSpanSuccess(span);
-                recordMcpToolCall(name, durationMs, "success");
+                recordMcpToolCall(name, durationMs, "success", sessionId);
                 return result;
             }
             catch (error) {
                 const durationMs = performance.now() - start;
                 const errorType = error instanceof Error ? error.constructor.name : "UnknownError";
                 endSpanError(span, error);
-                recordMcpToolCall(name, durationMs, "error");
+                recordMcpToolCall(name, durationMs, "error", sessionId);
                 recordMcpToolError(name, errorType);
                 throw error;
             }
@@ -154,7 +189,7 @@ server, options = {}) {
                     options.onResourceRead(span, uri);
                 }
                 try {
-                    const result = await originalHandler(...handlerArgs);
+                    const result = await context.with(trace.setSpan(parentCtx, span), () => originalHandler(...handlerArgs));
                     endSpanSuccess(span);
                     recordMcpResourceRead(uri);
                     return result;
@@ -185,7 +220,7 @@ server, options = {}) {
                     parentContext: parentCtx,
                 });
                 try {
-                    const result = await originalHandler(...handlerArgs);
+                    const result = await context.with(trace.setSpan(parentCtx, span), () => originalHandler(...handlerArgs));
                     endSpanSuccess(span);
                     return result;
                 }
@@ -197,6 +232,13 @@ server, options = {}) {
             return originalPrompt(name, ...rest);
         };
     }
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        recordMcpSessionEnd();
+    };
 }
 /**
  * Trace a sampling/createMessage call (server → client LLM request).
@@ -227,6 +269,9 @@ export async function traceSampling(fn, options) {
         serverName: options.serverName ?? "mcp-server",
         serverVersion: options.serverVersion ?? "unknown",
         parentContext: options.parentContext,
+        sessionId: options.sessionId,
+        protocolVersion: options.protocolVersion,
+        networkTransport: options.networkTransport,
     });
     if (options.maxTokens !== undefined) {
         span.setAttribute("gen_ai.request.max_tokens", options.maxTokens);

package/dist/mcp/spans.d.ts

@@ -1,18 +1,28 @@
 /**
  * OTel span creation for MCP operations.
  *
- * Maps MCP methods to OTel GenAI semantic conventions:
- * - tools/call              → execute_tool {tool_name}
- * - resources/read          → retrieval {uri}
- * - prompts/get             → prompt {name}
- * - sampling/createMessage  → chat {model}
+ * Follows OTel MCP semantic conventions (PR #2083):
+ * - tools/call              → `tools/call {tool_name}`
+ * - resources/read          → `resources/read {uri}`
+ * - prompts/get             → `prompts/get {name}`
+ * - sampling/createMessage  → `sampling/createMessage {model}`
  */
 import { type Context } from "@opentelemetry/api";
 declare const tracer: import("@opentelemetry/api").Tracer;
+/** MCP method names per OTel semconv. */
+export declare const MCP_METHODS: {
+    readonly TOOLS_CALL: "tools/call";
+    readonly RESOURCES_READ: "resources/read";
+    readonly PROMPTS_GET: "prompts/get";
+    readonly SAMPLING_CREATE_MESSAGE: "sampling/createMessage";
+};
 export interface SpanOptions {
     readonly serverName: string;
     readonly serverVersion: string;
     readonly parentContext: Context;
+    readonly sessionId?: string | undefined;
+    readonly protocolVersion?: string | undefined;
+    readonly networkTransport?: string | undefined;
 }
 export declare function startToolSpan(toolName: string, options: SpanOptions): import("@opentelemetry/api").Span;
 export declare function startResourceSpan(uri: string, options: SpanOptions): import("@opentelemetry/api").Span;
@@ -21,6 +31,9 @@ export interface SamplingSpanOptions {
     readonly serverName: string;
     readonly serverVersion: string;
     readonly parentContext?: Context | undefined;
+    readonly sessionId?: string | undefined;
+    readonly protocolVersion?: string | undefined;
+    readonly networkTransport?: string | undefined;
 }
 export declare function startSamplingSpan(model: string, options: SamplingSpanOptions): import("@opentelemetry/api").Span;
 export declare function endSpanSuccess(span: ReturnType<typeof tracer.startSpan>): void;