feat: add SERVER spans to OpenTelemetry tracing

Instrument the server side of MCP request handling with OpenTelemetry
SERVER spans. The span starts after request validation in _receive_loop
and ends when RequestResponder.respond() or cancel() is called, covering
the full server-side request lifecycle.

Author: Kludex

src/mcp/shared/session.py

@@ -8,13 +8,14 @@
 
 import anyio
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from opentelemetry import trace
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import Self
 
 from mcp.shared.exceptions import MCPError
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata, SessionMessage
 from mcp.shared.response_router import ResponseRouter
-from mcp.shared.tracing import end_span_error, end_span_ok, start_client_span
+from mcp.shared.tracing import end_span_error, end_span_ok, start_client_span, start_server_span
 from mcp.types import (
     CONNECTION_CLOSED,
     INVALID_PARAMS,
@@ -78,6 +79,7 @@ def __init__(
         session: BaseSession[SendRequestT, SendNotificationT, SendResultT, ReceiveRequestT, ReceiveNotificationT],
         on_complete: Callable[[RequestResponder[ReceiveRequestT, SendResultT]], Any],
         message_metadata: MessageMetadata = None,
+        span: trace.Span | None = None,
     ) -> None:
         self.request_id = request_id
         self.request_meta = request_meta
@@ -88,6 +90,7 @@ def __init__(
         self._cancel_scope = anyio.CancelScope()
         self._on_complete = on_complete
         self._entered = False  # Track if we're in a context manager
+        self._span = span
 
     def __enter__(self) -> RequestResponder[ReceiveRequestT, SendResultT]:
         """Enter the context manager, enabling request cancellation tracking."""
@@ -127,6 +130,12 @@ async def respond(self, response: SendResultT | ErrorData) -> None:
         if not self.cancelled:  # pragma: no branch
             self._completed = True
 
+            if self._span is not None:
+                if isinstance(response, ErrorData):
+                    end_span_error(self._span, MCPError(code=response.code, message=response.message))
+                else:
+                    end_span_ok(self._span)
+
             await self._session._send_response(  # type: ignore[reportPrivateUsage]
                 request_id=self.request_id, response=response
             )
@@ -140,6 +149,10 @@ async def cancel(self) -> None:
 
         self._cancel_scope.cancel()
         self._completed = True  # Mark as completed so it's removed from in_flight
+
+        if self._span is not None:
+            end_span_error(self._span, MCPError(code=0, message="Request cancelled"))
+
         # Send an error response to indicate cancellation
         await self._session._send_response(  # type: ignore[reportPrivateUsage]
             request_id=self.request_id,
@@ -351,13 +364,19 @@ async def _receive_loop(self) -> None:
                                 message.message.model_dump(by_alias=True, mode="json", exclude_none=True),
                                 by_name=False,
                             )
+                            request_data = message.message.model_dump(by_alias=True, mode="json", exclude_none=True)
+                            server_span = start_server_span(
+                                request_data.get("method", ""),
+                                request_data.get("params"),
+                            )
                             responder = RequestResponder(
                                 request_id=message.message.id,
                                 request_meta=validated_request.params.meta if validated_request.params else None,
                                 request=validated_request,
                                 session=self,
                                 on_complete=lambda r: self._in_flight.pop(r.request_id, None),
                                 message_metadata=message.metadata,
+                                span=server_span,
                             )
                             self._in_flight[responder.request_id] = responder
                             await self._received_request(responder)

src/mcp/shared/tracing.py

@@ -50,6 +50,24 @@ def start_client_span(method: str, params: dict[str, Any] | None) -> trace.Span
     return span
 
 
+def start_server_span(method: str, params: dict[str, Any] | None) -> trace.Span | None:
+    """Start a SERVER span for an incoming MCP request.
+
+    Returns None if the method is excluded from tracing.
+    """
+    if method in _EXCLUDED_METHODS:
+        return None
+
+    target = _extract_target(method, params)
+    span_name = f"{method} {target}" if target else method
+    span = _tracer.start_span(
+        span_name,
+        kind=trace.SpanKind.SERVER,
+        attributes={ATTR_MCP_METHOD_NAME: method},
+    )
+    return span
+
+
 def end_span_ok(span: trace.Span) -> None:
     """Mark a span as successful and end it."""
     span.set_status(StatusCode.OK)

tests/shared/test_tracing.py

@@ -42,8 +42,12 @@ async def test_span_created_on_send_request(_otel_setup: InMemorySpanExporter) -
         await client.send_ping()
 
     spans = exporter.get_finished_spans()
-    # Filter to only the ping span (initialize also produces one)
-    ping_spans = [s for s in spans if s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "ping"]
+    # Filter to only the CLIENT ping span (initialize also produces one, plus server spans)
+    ping_spans = [
+        s
+        for s in spans
+        if s.kind == SpanKind.CLIENT and s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "ping"
+    ]
     assert len(ping_spans) == 1
 
     span = ping_spans[0]
@@ -71,7 +75,11 @@ async def handle_call_tool(name: str, arguments: dict[str, Any] | None) -> list[
         await client.call_tool("echo", {"msg": "hi"})
 
     spans = exporter.get_finished_spans()
-    tool_spans = [s for s in spans if s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "tools/call"]
+    tool_spans = [
+        s
+        for s in spans
+        if s.kind == SpanKind.CLIENT and s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "tools/call"
+    ]
     assert len(tool_spans) == 1
 
     span = tool_spans[0]
@@ -104,7 +112,11 @@ async def handle_call_tool(name: str, arguments: dict[str, Any] | None) -> list[
             )
 
     spans = exporter.get_finished_spans()
-    tool_spans = [s for s in spans if s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "tools/call"]
+    tool_spans = [
+        s
+        for s in spans
+        if s.kind == SpanKind.CLIENT and s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "tools/call"
+    ]
     assert len(tool_spans) == 1
 
     span = tool_spans[0]
@@ -127,3 +139,85 @@ async def test_no_span_for_excluded_method(_otel_setup: InMemorySpanExporter) ->
         s for s in spans if s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "notifications/message"
     ]
     assert len(excluded_spans) == 0
+
+
+@pytest.mark.anyio
+async def test_server_span_on_successful_request(_otel_setup: InMemorySpanExporter) -> None:
+    """Verify a SERVER span is created when the server handles a request."""
+    exporter = _otel_setup
+
+    server = Server(name="test server")
+    async with Client(server) as client:
+        await client.send_ping()
+
+    spans = exporter.get_finished_spans()
+    server_ping_spans = [
+        s
+        for s in spans
+        if s.kind == SpanKind.SERVER and s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "ping"
+    ]
+    assert len(server_ping_spans) == 1
+
+    span = server_ping_spans[0]
+    assert span.name == "ping"
+    assert span.status.status_code == StatusCode.OK
+
+
+@pytest.mark.anyio
+async def test_server_span_includes_target(_otel_setup: InMemorySpanExporter) -> None:
+    """Verify server span name includes tool name for tools/call requests."""
+    exporter = _otel_setup
+
+    server = Server(name="test server")
+
+    @server.list_tools()
+    async def handle_list_tools() -> list[types.Tool]:
+        return [types.Tool(name="echo", description="Echo tool", input_schema={"type": "object"})]
+
+    @server.call_tool()
+    async def handle_call_tool(name: str, arguments: dict[str, Any] | None) -> list[types.TextContent]:
+        return [types.TextContent(type="text", text=str(arguments))]
+
+    async with Client(server) as client:
+        await client.call_tool("echo", {"msg": "hi"})
+
+    spans = exporter.get_finished_spans()
+    server_tool_spans = [
+        s
+        for s in spans
+        if s.kind == SpanKind.SERVER and s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "tools/call"
+    ]
+    assert len(server_tool_spans) == 1
+
+    span = server_tool_spans[0]
+    assert span.name == "tools/call echo"
+    assert span.status.status_code == StatusCode.OK
+
+
+@pytest.mark.anyio
+async def test_server_span_error_on_error_response(_otel_setup: InMemorySpanExporter) -> None:
+    """Verify server span records ERROR status when the server responds with ErrorData."""
+    exporter = _otel_setup
+
+    server = Server(name="test server")
+
+    @server.list_tools()
+    async def handle_list_tools() -> list[types.Tool]:
+        raise MCPError(code=-1, message="internal failure")
+
+    async with Client(server) as client:
+        with pytest.raises(MCPError, match="internal failure"):
+            await client.list_tools()
+
+    spans = exporter.get_finished_spans()
+    server_spans = [
+        s
+        for s in spans
+        if s.kind == SpanKind.SERVER and s.attributes and s.attributes.get(ATTR_MCP_METHOD_NAME) == "tools/list"
+    ]
+    assert len(server_spans) == 1
+
+    span = server_spans[0]
+    assert span.status.status_code == StatusCode.ERROR
+    assert span.attributes is not None
+    assert span.attributes.get(ATTR_ERROR_TYPE) == "MCPError"