Add GenAI semantic-convention attributes to OpenTelemetryMiddleware

Kludex · Kludex · commit cdd6bb22551d · 2026-06-25T15:47:29.000+02:00
Set gen_ai.operation.name (execute_tool), gen_ai.tool.name, and
gen_ai.prompt.name per the MCP OTel semantic conventions, plus error.type
and rpc.response.status_code on failures (tool_error for a tools/call
result carrying is_error). Span name now follows {mcp.method.name} {target}.
diff --git a/src/mcp/server/_otel.py b/src/mcp/server/_otel.py
@@ -8,44 +8,70 @@
 from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
 from mcp.shared._otel import extract_trace_context, otel_span
 from mcp.shared.exceptions import MCPError
+from mcp.types import CallToolResult
 
 
 class OpenTelemetryMiddleware(ServerMiddleware[Any]):
     """Context-tier middleware that wraps each inbound message in an OpenTelemetry span.
 
-    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. Requests and notifications both get a span;
-    `jsonrpc.request.id` is set only when `ctx.request_id` is present (notifications
-    have none).
+    Span name `"<method> [<target>]"`, `mcp.method.name` attribute, W3C trace context extracted from
+    `params._meta` (SEP-414), and an ERROR status if the handler raises. Requests and notifications both get a span;
+    `jsonrpc.request.id` is set only when `ctx.request_id` is present (notifications have none).
+
+    Tool and prompt operations additionally carry the GenAI semantic-convention attributes `gen_ai.tool.name` /
+    `gen_ai.prompt.name`, and `gen_ai.operation.name` is set to `execute_tool` for `tools/call`. Failures set
+    `error.type` and `rpc.response.status_code` to the JSON-RPC error code, or `error.type` to `tool_error` for a
+    `tools/call` result carrying `is_error`.
     """
 
     async def __call__(self, ctx: ServerRequestContext[Any, Any], call_next: CallNext) -> HandlerResult:
         name = ctx.params.get("name") if ctx.params else None
         target = name if isinstance(name, str) else None
 
-        attributes: dict[str, Any] = {"mcp.method.name": ctx.method}
+        attributes: dict[str, Any] = {
+            "mcp.method.name": ctx.method,
+            "mcp.protocol.version": ctx.protocol_version,
+        }
         if ctx.request_id is not None:
             attributes["jsonrpc.request.id"] = str(ctx.request_id)
 
+        if target is not None:
+            if ctx.method == "tools/call":
+                attributes["gen_ai.operation.name"] = "execute_tool"
+                attributes["gen_ai.tool.name"] = target
+            elif ctx.method == "prompts/get":
+                attributes["gen_ai.prompt.name"] = target
+
         with otel_span(
-            name=f"MCP handle {ctx.method}{f' {target}' if target else ''}",
+            name=f"{ctx.method}{f' {target}' if target else ''}",
             kind=SpanKind.SERVER,
             attributes=attributes,
             context=extract_trace_context(ctx.meta),
             record_exception=False,
             set_status_on_exception=False,
         ) as span:
             try:
-                return await call_next(ctx)
+                result = await call_next(ctx)
             except MCPError as e:
+                code = str(e.error.code)
+                span.set_attributes({"error.type": code, "rpc.response.status_code": code})
                 span.set_status(StatusCode.ERROR, e.error.message)
                 raise
             except ValidationError:
                 # Mirror the sanitized wire response; pydantic messages carry client input.
+                span.set_attribute("error.type", "ValidationError")
                 span.set_status(StatusCode.ERROR, "Invalid request parameters")
                 raise
             except Exception as e:
+                span.set_attribute("error.type", type(e).__qualname__)
                 span.record_exception(e)
                 span.set_status(StatusCode.ERROR, str(e))
                 raise
+            if ctx.method == "tools/call":
+                match result:
+                    case CallToolResult(is_error=True) | {"isError": True} | {"is_error": True}:
+                        span.set_attribute("error.type", "tool_error")
+                        span.set_status(StatusCode.ERROR)
+                    case _:
+                        pass
+            return result
diff --git a/tests/server/test_otel.py b/tests/server/test_otel.py
@@ -13,7 +13,16 @@
 from mcp.server.runner import otel_middleware
 from mcp.shared._otel import inject_trace_context
 from mcp.shared.exceptions import MCPError
-from mcp.types import CallToolRequestParams, ListToolsResult, NotificationParams, PaginatedRequestParams, Tool
+from mcp.types import (
+    CallToolRequestParams,
+    CallToolResult,
+    GetPromptRequestParams,
+    GetPromptResult,
+    ListToolsResult,
+    NotificationParams,
+    PaginatedRequestParams,
+    Tool,
+)
 
 from .conftest import SpanCapture
 from .test_runner import Ctx, SrvT, connected_runner
@@ -40,13 +49,98 @@ async def test_emits_server_span_with_method_and_target(server: SrvT, spans: Spa
         result = await client.send_raw_request("tools/call", {"name": "mytool", "arguments": {}})
     assert result == {"content": [], "isError": False}
     [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
-    assert span.name == "MCP handle tools/call mytool"
+    assert span.name == "tools/call mytool"
     assert span.attributes is not None
     assert span.attributes["mcp.method.name"] == "tools/call"
+    assert span.attributes["gen_ai.operation.name"] == "execute_tool"
+    assert span.attributes["gen_ai.tool.name"] == "mytool"
     assert isinstance(span.attributes["jsonrpc.request.id"], str)
     assert span.status.status_code == StatusCode.UNSET
 
 
+@pytest.mark.anyio
+async def test_tool_error_dict_result_sets_error_type(server: SrvT, spans: SpanCapture):
+    async def err_tool(ctx: Ctx, params: CallToolRequestParams) -> dict[str, Any]:
+        return {"content": [], "isError": True}
+
+    server.add_request_handler("tools/call", CallToolRequestParams, err_tool)
+    server.middleware.append(OpenTelemetryMiddleware())
+    async with connected_runner(server) as (client, _):
+        spans.clear()
+        await client.send_raw_request("tools/call", {"name": "mytool", "arguments": {}})
+    [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
+    assert span.attributes is not None
+    assert span.attributes["error.type"] == "tool_error"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+@pytest.mark.anyio
+async def test_tool_error_model_result_sets_error_type(server: SrvT, spans: SpanCapture):
+    async def err_tool(ctx: Ctx, params: CallToolRequestParams) -> CallToolResult:
+        return CallToolResult(content=[], is_error=True)
+
+    server.add_request_handler("tools/call", CallToolRequestParams, err_tool)
+    server.middleware.append(OpenTelemetryMiddleware())
+    async with connected_runner(server) as (client, _):
+        spans.clear()
+        await client.send_raw_request("tools/call", {"name": "mytool", "arguments": {}})
+    [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
+    assert span.attributes is not None
+    assert span.attributes["error.type"] == "tool_error"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+@pytest.mark.anyio
+async def test_tool_error_snake_case_dict_result_sets_error_type(server: SrvT, spans: SpanCapture):
+    async def err_tool(ctx: Ctx, params: CallToolRequestParams) -> dict[str, Any]:
+        return {"content": [], "is_error": True}
+
+    server.add_request_handler("tools/call", CallToolRequestParams, err_tool)
+    server.middleware.append(OpenTelemetryMiddleware())
+    async with connected_runner(server) as (client, _):
+        spans.clear()
+        await client.send_raw_request("tools/call", {"name": "mytool", "arguments": {}})
+    [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
+    assert span.attributes is not None
+    assert span.attributes["error.type"] == "tool_error"
+    assert span.status.status_code == StatusCode.ERROR
+
+
+@pytest.mark.anyio
+async def test_named_non_tool_prompt_method_omits_gen_ai_attrs(server: SrvT, spans: SpanCapture):
+    async def custom(ctx: Ctx, params: CallToolRequestParams) -> dict[str, Any]:
+        return {"content": [], "isError": False}
+
+    server.add_request_handler("custom/op", CallToolRequestParams, custom)
+    server.middleware.append(OpenTelemetryMiddleware())
+    async with connected_runner(server) as (client, _):
+        spans.clear()
+        await client.send_raw_request("custom/op", {"name": "thing", "arguments": {}})
+    [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
+    assert span.name == "custom/op thing"
+    assert span.attributes is not None
+    assert "gen_ai.operation.name" not in span.attributes
+    assert "gen_ai.tool.name" not in span.attributes
+    assert "gen_ai.prompt.name" not in span.attributes
+
+
+@pytest.mark.anyio
+async def test_prompt_get_sets_prompt_name(server: SrvT, spans: SpanCapture):
+    async def get_prompt(ctx: Ctx, params: GetPromptRequestParams) -> GetPromptResult:
+        return GetPromptResult(messages=[])
+
+    server.add_request_handler("prompts/get", GetPromptRequestParams, get_prompt)
+    server.middleware.append(OpenTelemetryMiddleware())
+    async with connected_runner(server) as (client, _):
+        spans.clear()
+        await client.send_raw_request("prompts/get", {"name": "myprompt"})
+    [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
+    assert span.name == "prompts/get myprompt"
+    assert span.attributes is not None
+    assert span.attributes["gen_ai.prompt.name"] == "myprompt"
+    assert "gen_ai.operation.name" not in span.attributes
+
+
 @pytest.mark.anyio
 async def test_notification_span_omits_request_id(server: SrvT, spans: SpanCapture):
     async def on_roots(ctx: Ctx, params: NotificationParams | None) -> None:
@@ -59,7 +153,7 @@ async def on_roots(ctx: Ctx, params: NotificationParams | None) -> None:
         await client.notify("notifications/roots/list_changed", None)
         await anyio.wait_all_tasks_blocked()
     [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
-    assert span.name == "MCP handle notifications/roots/list_changed"
+    assert span.name == "notifications/roots/list_changed"
     assert span.attributes is not None
     assert span.attributes["mcp.method.name"] == "notifications/roots/list_changed"
     assert "jsonrpc.request.id" not in span.attributes
@@ -146,6 +240,9 @@ async def test_records_error_status_on_mcp_error(server: SrvT, spans: SpanCaptur
     [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
     assert span.status.status_code == StatusCode.ERROR
     assert span.status.description == "Method not found"
+    assert span.attributes is not None
+    assert span.attributes["error.type"] == str(exc.value.error.code)
+    assert span.attributes["rpc.response.status_code"] == str(exc.value.error.code)
     assert not [e for e in span.events if e.name == "exception"]
 
 
@@ -160,6 +257,8 @@ async def test_validation_failure_sets_sanitized_status(server: SrvT, spans: Spa
     [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
     assert span.status.status_code == StatusCode.ERROR
     assert span.status.description == "Invalid request parameters"
+    assert span.attributes is not None
+    assert span.attributes["error.type"] == "ValidationError"
     assert not span.events
 
 
@@ -177,6 +276,8 @@ async def failing(ctx: Ctx, params: PaginatedRequestParams | None) -> Any:
     [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
     assert span.status.status_code == StatusCode.ERROR
     assert span.status.description == "handler blew up"
+    assert span.attributes is not None
+    assert span.attributes["error.type"] == "ValueError"
     [event] = [e for e in span.events if e.name == "exception"]
     assert event.attributes is not None
     assert event.attributes["exception.type"] == "ValueError"
@@ -202,4 +303,4 @@ async def inject_arg(ctx: Ctx, call_next: CallNext) -> Any:
         await client.send_raw_request("tools/call", {"name": "mytool", "arguments": {"x": 1}})
     assert seen_arguments == {"x": 1, "injected": True}
     [span] = [s for s in spans.finished() if s.kind == SpanKind.SERVER]
-    assert span.name == "MCP handle tools/call mytool"
+    assert span.name == "tools/call mytool"
