Add GenAI semconv attributes to native OTel spans

Author: etserend

src/mcp/server/runner.py

@@ -30,7 +30,7 @@
 from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
 from mcp.server.models import InitializationOptions
 from mcp.server.session import ServerSession
-from mcp.shared._otel import extract_trace_context, otel_span
+from mcp.shared._otel import build_span_attributes, extract_trace_context, otel_span
 from mcp.shared.dispatcher import DispatchContext, DispatchMiddleware, OnRequest
 from mcp.shared.exceptions import MCPError
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
@@ -91,10 +91,10 @@ def _extract_meta(params: Mapping[str, Any] | None) -> RequestParamsMeta | None:
 def otel_middleware(next_on_request: OnRequest) -> OnRequest:
     """Dispatch-tier middleware that wraps each request in an OpenTelemetry span.
 
-    Mirrors the span shape of the existing `Server._handle_request`: span name
-    `"MCP handle <method> [<target>]"`, `mcp.method.name` attribute, W3C
-    trace context extracted from `params._meta` (SEP-414), and an ERROR
-    status if the handler raises.
+    Span name: `"MCP handle <method> [<target>]"`. Attributes follow the GenAI
+    semconv for MCP: `gen_ai.operation.name`, `gen_ai.tool.name`, `rpc.system`,
+    `mcp.method.name`, `jsonrpc.request.id`. W3C trace context is extracted from
+    `params._meta` (SEP-414) to parent the span under the client span.
     """
 
     async def wrapped(
@@ -114,7 +114,7 @@ async def wrapped(
                 parent = None
         span_name = f"MCP handle {method}{f' {target}' if target else ''}"
         # `otel_middleware` wraps `on_request` only, so `request_id` is always set.
-        attributes = {"mcp.method.name": method, "jsonrpc.request.id": str(dctx.request_id)}
+        attributes = build_span_attributes(method, dctx.request_id, params=params)
         with otel_span(
             span_name,
             kind=SpanKind.SERVER,

src/mcp/shared/_otel.py

@@ -12,6 +12,66 @@
 
 _tracer = get_tracer("mcp-python-sdk")
 
+# Maps MCP JSON-RPC method names to GenAI semantic convention operation names.
+# https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md
+_METHOD_TO_GEN_AI_OPERATION: dict[str, str] = {
+    "tools/call": "execute_tool",
+    "tools/list": "list_tools",
+    "resources/read": "read_resource",
+    "resources/list": "list_resources",
+    "resources/templates/list": "list_resources",
+    "prompts/get": "get_prompt",
+    "prompts/list": "list_prompts",
+}
+
+
+def build_span_attributes(
+    method: str,
+    request_id: Any,
+    *,
+    params: dict[str, Any] | None = None,
+    server_name: str | None = None,
+    session_id: str | None = None,
+) -> dict[str, Any]:
+    """Build OTel span attributes for an MCP request.
+
+    Produces the base set of semantic convention attributes shared by both
+    client (`SpanKind.CLIENT`) and server (`SpanKind.SERVER`) spans.
+    Pass `server_name` and `session_id` for server-side spans.
+    """
+    attrs: dict[str, Any] = {
+        "rpc.system": "mcp",
+        "mcp.method.name": method,
+        "jsonrpc.request.id": str(request_id),
+    }
+
+    operation = _METHOD_TO_GEN_AI_OPERATION.get(method)
+    if operation is not None:
+        attrs["gen_ai.operation.name"] = operation
+
+    if server_name is not None:
+        attrs["rpc.service"] = server_name
+
+    if params is not None:
+        # gen_ai.tool.name — present on tools/call, prompts/get
+        name = params.get("name")
+        if isinstance(name, str):
+            attrs["gen_ai.tool.name"] = name
+
+        # mcp.resource.uri — present on resources/read; also on completion/complete via ref.uri
+        uri = params.get("uri")
+        if uri is None:
+            ref = params.get("ref")
+            if isinstance(ref, dict):
+                uri = ref.get("uri")
+        if uri is not None:
+            attrs["mcp.resource.uri"] = str(uri)
+
+    if session_id is not None:
+        attrs["mcp.session.id"] = session_id
+
+    return attrs
+
 
 @contextmanager
 def otel_span(

src/mcp/shared/jsonrpc_dispatcher.py

@@ -32,7 +32,7 @@
 from opentelemetry.trace import SpanKind
 from pydantic import ValidationError
 
-from mcp.shared._otel import inject_trace_context, otel_span
+from mcp.shared._otel import build_span_attributes, inject_trace_context, otel_span
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.dispatcher import CallOptions, Dispatcher, OnNotify, OnRequest, ProgressFnT
 from mcp.shared.exceptions import MCPError, NoBackChannelError
@@ -334,7 +334,7 @@ async def send_raw_request(
             with otel_span(
                 span_name,
                 kind=SpanKind.CLIENT,
-                attributes={"mcp.method.name": method, "jsonrpc.request.id": str(request_id)},
+                attributes=build_span_attributes(method, request_id, params=out_params),
             ):
                 # Inject W3C trace context into _meta (SEP-414). With a no-op
                 # tracer this writes nothing, but `_meta` itself is still

src/mcp/shared/session.py

@@ -13,7 +13,7 @@
 from typing_extensions import Self
 
 from mcp.shared._compat import resync_tracer
-from mcp.shared._otel import inject_trace_context, otel_span
+from mcp.shared._otel import build_span_attributes, inject_trace_context, otel_span
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.exceptions import MCPError
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata, SessionMessage
@@ -219,7 +219,11 @@ async def send_request(
             with otel_span(
                 span_name,
                 kind=SpanKind.CLIENT,
-                attributes={"mcp.method.name": request.method, "jsonrpc.request.id": str(request_id)},
+                attributes=build_span_attributes(
+                    request.method,
+                    request_id,
+                    params=request_data.get("params"),
+                ),
             ):
                 # Inject W3C trace context into _meta (SEP-414).
                 meta: dict[str, Any] = request_data.setdefault("params", {}).setdefault("_meta", {})

tests/shared/test_otel.py

@@ -34,8 +34,68 @@ def greet(name: str) -> str:
     client_span = next(s for s in spans if s["name"] == "MCP send tools/call greet")
     server_span = next(s for s in spans if s["name"] == "MCP handle tools/call greet")
 
+    # Base RPC + MCP attributes
+    assert client_span["attributes"]["rpc.system"] == "mcp"
     assert client_span["attributes"]["mcp.method.name"] == "tools/call"
+    assert client_span["attributes"]["jsonrpc.request.id"] is not None
+    assert server_span["attributes"]["rpc.system"] == "mcp"
     assert server_span["attributes"]["mcp.method.name"] == "tools/call"
 
+    # GenAI semconv attributes
+    assert client_span["attributes"]["gen_ai.operation.name"] == "execute_tool"
+    assert client_span["attributes"]["gen_ai.tool.name"] == "greet"
+    assert server_span["attributes"]["gen_ai.operation.name"] == "execute_tool"
+    assert server_span["attributes"]["gen_ai.tool.name"] == "greet"
+
     # Server span should be in the same trace as the client span (context propagation).
     assert server_span["context"]["trace_id"] == client_span["context"]["trace_id"]
+
+
+async def test_list_tools_spans(capfire: CaptureLogfire):
+    """Verify that listing tools produces spans with list_tools operation."""
+    server = MCPServer("test")
+
+    @server.tool()
+    def greet(name: str) -> str:
+        """Greet someone."""
+        return f"Hello, {name}!"
+
+    async with Client(server) as client:
+        await client.list_tools()
+
+    spans = capfire.exporter.exported_spans_as_dict()
+
+    client_span = next(s for s in spans if s["name"] == "MCP send tools/list")
+    server_span = next(s for s in spans if s["name"] == "MCP handle tools/list")
+
+    assert client_span["attributes"]["gen_ai.operation.name"] == "list_tools"
+    assert server_span["attributes"]["gen_ai.operation.name"] == "list_tools"
+    # No tool name on list — no specific tool targeted
+    assert "gen_ai.tool.name" not in client_span["attributes"]
+    assert "gen_ai.tool.name" not in server_span["attributes"]
+
+    assert server_span["context"]["trace_id"] == client_span["context"]["trace_id"]
+
+
+async def test_resource_read_spans(capfire: CaptureLogfire):
+    """Verify that reading a resource produces spans with resource URI."""
+    server = MCPServer("test")
+
+    @server.resource("test://greeting")
+    def greeting() -> str:
+        return "hello"
+
+    async with Client(server) as client:
+        await client.read_resource("test://greeting")
+
+    spans = capfire.exporter.exported_spans_as_dict()
+
+    client_span = next(s for s in spans if s["name"] == "MCP send resources/read")
+    server_span = next(s for s in spans if s["name"] == "MCP handle resources/read")
+
+    assert client_span["attributes"]["gen_ai.operation.name"] == "read_resource"
+    assert client_span["attributes"]["mcp.resource.uri"] == "test://greeting"
+    assert server_span["attributes"]["gen_ai.operation.name"] == "read_resource"
+    assert server_span["attributes"]["mcp.resource.uri"] == "test://greeting"
+
+    assert server_span["context"]["trace_id"] == client_span["context"]["trace_id"]