Add MCP semantic conventions to otelv2

litellm/integrations/otel/__init__.py

@@ -32,20 +32,28 @@ class (from :mod:`logger`).
     LLMCallSpanData,
     LLMRequestParams,
     LLMUsage,
+    MCPToolCallSpanData,
     ProxyRequestSpanData,
     ServerInfo,
     ServiceSpanData,
     SpanError,
+    is_mcp_tool_call,
 )
 from litellm.integrations.otel.model.semconv import (
     DB,
+    HTTP,
+    MCP,
+    Client,
     Error,
     GenAI,
     GenAIOperation,
     GenAIProvider,
-    HTTP,
+    JsonRpc,
     LiteLLM,
+    MCPMethod,
     Metric,
+    Network,
+    NetworkTransport,
     Server,
     resolve_operation,
     resolve_provider,
@@ -69,13 +77,19 @@ class (from :mod:`logger`).
     "BAGGAGE_PROMOTED_KEYS",
     "DB",
     "DEFAULT_BAGGAGE_METADATA_KEYS",
+    "Client",
     "Error",
     "GenAI",
     "GenAIOperation",
     "GenAIProvider",
     "HTTP",
+    "JsonRpc",
     "LiteLLM",
+    "MCP",
+    "MCPMethod",
     "Metric",
+    "Network",
+    "NetworkTransport",
     "Server",
     "resolve_operation",
     "resolve_provider",
@@ -92,11 +106,13 @@ class (from :mod:`logger`).
     "LLMCallSpanData",
     "LLMRequestParams",
     "LLMUsage",
+    "MCPToolCallSpanData",
     "ProxyRequestSpanData",
     "RequestContext",
     "RequestIdentity",
     "ServerInfo",
     "ServiceSpanData",
     "SpanError",
+    "is_mcp_tool_call",
     "promoted_baggage",
 ]

litellm/integrations/otel/emitter.py

@@ -13,6 +13,7 @@
 from litellm.integrations.otel.model.payloads import (
     GuardrailSpanData,
     LLMCallSpanData,
+    MCPToolCallSpanData,
     ServiceSpanData,
 )
 from litellm.integrations.otel.plumbing.providers import to_otel_span_kind
@@ -22,6 +23,7 @@
     SpanRole,
     guardrail_span_name,
     llm_call_span_name,
+    mcp_tool_call_span_name,
     service_span_name,
 )
 
@@ -30,6 +32,7 @@
 # have no builder here.
 _NAME_BUILDERS: dict[SpanRole, Callable[..., str]] = {
     SpanRole.LLM_CALL: llm_call_span_name,
+    SpanRole.MCP_TOOL_CALL: mcp_tool_call_span_name,
     SpanRole.GUARDRAIL: guardrail_span_name,
     # DB_CALL and SERVICE are both built from ServiceSpanData; they differ only in
     # span kind (CLIENT vs INTERNAL) and attribute vocabulary, not in naming.
@@ -121,10 +124,14 @@ def emit(
         Return the span, or ``None`` if it was deduplicated away. ``tracer``
         overrides the bound tracer for this span, used for per-request routing.
         """
-        # Only LLM-call spans carry a dedup key; LLM-call and service spans
-        # carry an ``error`` field. ``isinstance`` narrows the type for mypy and
-        # keeps the engine free of duck-typed attribute reads.
-        dedup_key = data.identity.call_id if isinstance(data, LLMCallSpanData) else None
+        # LLM-call and MCP tool-call spans carry a dedup key (their request's
+        # call id), so a sync+async double-firing coalesces. ``isinstance`` narrows
+        # the type for mypy and keeps the engine free of duck-typed attribute reads.
+        dedup_key = (
+            data.identity.call_id
+            if isinstance(data, (LLMCallSpanData, MCPToolCallSpanData))
+            else None
+        )
         if self._seen(dedup_key, role):
             return None
         span = self.start_span(
@@ -160,7 +167,15 @@ def finish_span(
                 span.set_attribute(key, value)
         error = (
             data.error
-            if isinstance(data, (LLMCallSpanData, ServiceSpanData, GuardrailSpanData))
+            if isinstance(
+                data,
+                (
+                    LLMCallSpanData,
+                    MCPToolCallSpanData,
+                    ServiceSpanData,
+                    GuardrailSpanData,
+                ),
+            )
             else None
         )
         if error and (error.error_type or error.message):

litellm/integrations/otel/logger.py

@@ -31,8 +31,10 @@
 from litellm.integrations.otel.model.payloads import (
     GuardrailSpanData,
     LLMCallSpanData,
+    MCPToolCallSpanData,
     ServiceSpanData,
     SpanError,
+    is_mcp_tool_call,
 )
 from litellm.integrations.otel.plumbing.providers import (
     build_tracer_provider,
@@ -43,7 +45,10 @@
 from litellm.integrations.otel.model.utils import to_ns
 
 if TYPE_CHECKING:
-    from litellm.types.utils import StandardLoggingGuardrailInformation
+    from litellm.types.utils import (
+        StandardLoggingGuardrailInformation,
+        StandardLoggingPayload,
+    )
 
 LITELLM_TRACER_NAME = "litellm"
 
@@ -200,11 +205,53 @@ def log_pre_api_call(self, model, messages, kwargs):
             self._open_llm_calls.popitem(last=False)
 
     async def async_log_success_event(self, kwargs, response_obj, start_time, end_time):
+        if self._emit_mcp_tool_call(kwargs, start_time, end_time):
+            return
         self._close_llm_call(kwargs, start_time, end_time)
 
     async def async_log_failure_event(self, kwargs, response_obj, start_time, end_time):
+        if self._emit_mcp_tool_call(kwargs, start_time, end_time):
+            return
         self._close_llm_call(kwargs, start_time, end_time)
 
+    def _emit_mcp_tool_call(
+        self,
+        kwargs: Mapping[str, Any],
+        start_time: datetime | float | None,
+        end_time: datetime | float | None,
+    ) -> bool:
+        """Emit an MCP tool-call span when the closed request was a tool call.
+
+        MCP tool calls reach the success/failure callbacks like any other request
+        (with ``call_type`` ``call_mcp_tool``), but they are not LLM calls and have
+        no ``pre_call`` carrier — so they get their own CLIENT span here, parented
+        to the request's server span. Returns whether it handled the event, so the
+        caller skips the LLM-call path. The whole span is emitted at once (there is
+        no boundary to open it at), deduped on the call id by the emitter.
+        """
+        raw_payload = kwargs.get("standard_logging_object")
+        if not raw_payload or not is_mcp_tool_call(
+            cast(Mapping[str, object], raw_payload)
+        ):
+            return False
+        payload = cast("StandardLoggingPayload", raw_payload)
+        data = MCPToolCallSpanData.from_standard_logging_payload(
+            payload, capture_content=self.config.capture_span_content
+        )
+        # A stray LLM carrier from a ``pre_call`` that mis-fired for this id would
+        # otherwise linger until evicted; drop it so it's neither leaked nor closed
+        # as a phantom LLM span.
+        if data.identity.call_id:
+            self._open_llm_calls.pop(data.identity.call_id, None)
+        self._emitter.emit(
+            SpanRole.MCP_TOOL_CALL,
+            data,
+            parent_context=resolve_request_span_context(),
+            start_time_ns=to_ns(start_time),
+            end_time_ns=to_ns(end_time),
+        )
+        return True
+
     def _close_llm_call(
         self,
         kwargs: Mapping[str, Any],

litellm/integrations/otel/mappers/base.py

@@ -7,6 +7,7 @@
 from litellm.integrations.otel.model.payloads import (
     GuardrailSpanData,
     LLMCallSpanData,
+    MCPToolCallSpanData,
     ServiceSpanData,
 )
 
@@ -21,7 +22,7 @@
 # The closed set of span-data types the engine routes through the mapper chain.
 # Server spans (PROXY_REQUEST + management routes) belong to the mounted FastAPI
 # instrumentor, not the mapper chain.
-SpanData = LLMCallSpanData | GuardrailSpanData | ServiceSpanData
+SpanData = LLMCallSpanData | MCPToolCallSpanData | GuardrailSpanData | ServiceSpanData
 
 
 @runtime_checkable

litellm/integrations/otel/mappers/genai.py

@@ -14,10 +14,18 @@
 from litellm.integrations.otel.model.payloads import (
     GuardrailSpanData,
     LLMCallSpanData,
+    MCPToolCallSpanData,
     ServiceSpanData,
     ToolDefinition,
 )
-from litellm.integrations.otel.model.semconv import DB, Error, GenAI, LiteLLM, Server
+from litellm.integrations.otel.model.semconv import (
+    DB,
+    MCP,
+    Error,
+    GenAI,
+    LiteLLM,
+    Server,
+)
 from litellm.integrations.otel.model.spans import db_system
 
 
@@ -64,6 +72,18 @@ class GenAIMapper:
         "parameters": lambda t: t.parameters_json or None,
     }
 
+    _MCP_ATTRS: dict[str, Callable[[MCPToolCallSpanData], AttrValue | None]] = {
+        GenAI.OPERATION_NAME: lambda d: d.operation.value,
+        MCP.METHOD_NAME: lambda d: d.method,
+        MCP.SESSION_ID: lambda d: d.session_id,
+        GenAI.TOOL_NAME: lambda d: d.tool_name or None,
+        GenAI.TOOL_CALL_ARGUMENTS: lambda d: d.arguments_json,
+        GenAI.TOOL_CALL_RESULT: lambda d: d.result_json,
+        LiteLLM.MCP_SERVER_NAME: lambda d: d.server_name,
+        LiteLLM.CALL_ID: lambda d: d.identity.call_id or None,
+        f"{LiteLLM.COST_PREFIX}total": lambda d: d.response_cost,
+    }
+
     _GUARDRAIL_ATTRS: dict[str, Callable[[GuardrailSpanData], AttrValue | None]] = {
         LiteLLM.GUARDRAIL_NAME: lambda d: d.guardrail_name,
         LiteLLM.GUARDRAIL_MODE: lambda d: d.mode,
@@ -92,6 +112,8 @@ def map(self, data: SpanData) -> AttributeMap:
         match data:
             case LLMCallSpanData():
                 return self._llm_call(data)
+            case MCPToolCallSpanData():
+                return collect(self._MCP_ATTRS, data)
             case GuardrailSpanData():
                 return self._guardrail(data)
             case ServiceSpanData():

litellm/integrations/otel/model/payloads.py

@@ -14,6 +14,7 @@
 )
 from litellm.integrations.otel.model.semconv import (
     GenAIOperation,
+    MCPMethod,
     resolve_operation,
     resolve_provider,
 )
@@ -35,11 +36,13 @@
     "LLMCallSpanData",
     "LLMRequestParams",
     "LLMUsage",
+    "MCPToolCallSpanData",
     "ProxyRequestSpanData",
     "ServerInfo",
     "ServiceSpanData",
     "SpanError",
     "ToolDefinition",
+    "is_mcp_tool_call",
 ]
 
 if TYPE_CHECKING:
@@ -309,6 +312,66 @@ def from_standard_logging_payload(
         )
 
 
+# --- the MCP tool-call model ------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class MCPToolCallSpanData:
+    """One MCP ``tools/call`` execution, parsed from a closed request's payload.
+
+    The proxy is an MCP *client* to the upstream server it forwards the call to,
+    so this is a CLIENT span. ``arguments_json``/``result_json`` are the tool's
+    input/output — sensitive content, so they're only retained when content
+    capture is enabled, mirroring ``LLMCallSpanData``'s message bodies.
+    """
+
+    operation: GenAIOperation
+    method: str
+    tool_name: str
+    server_name: str | None
+    session_id: str | None
+    arguments_json: str | None
+    result_json: str | None
+    error: SpanError | None
+    response_cost: float | None
+    identity: RequestIdentity
+
+    @classmethod
+    def from_standard_logging_payload(
+        cls, payload: "StandardLoggingPayload", capture_content: bool = False
+    ) -> "MCPToolCallSpanData":
+        meta = cast(Mapping[str, object], payload.get("mcp_tool_call_metadata") or {})
+        return cls(
+            operation=resolve_operation(as_str(payload.get("call_type"))),
+            method=MCPMethod.TOOLS_CALL.value,
+            tool_name=as_str(meta.get("name")) or "",
+            server_name=as_str(meta.get("mcp_server_name")),
+            session_id=as_str(meta.get("mcp_session_id")),
+            arguments_json=(
+                _json_or_none(meta.get("arguments"))
+                if capture_content and meta.get("arguments") is not None
+                else None
+            ),
+            result_json=(
+                _json_or_none(meta.get("result"))
+                if capture_content and meta.get("result") is not None
+                else None
+            ),
+            error=_parse_error(payload),
+            response_cost=as_float(payload.get("response_cost")),
+            identity=RequestContext.from_standard_logging_payload(payload).identity,
+        )
+
+
+def is_mcp_tool_call(payload: Mapping[str, object]) -> bool:
+    """Whether a closed request's payload is an MCP tool call rather than an LLM
+    call — true when the MCP gateway stamped its tool-call metadata, or the call
+    type says so on a path that hasn't populated the metadata yet."""
+    return bool(payload.get("mcp_tool_call_metadata")) or (
+        payload.get("call_type") == "call_mcp_tool"
+    )
+
+
 # --- service event_metadata sanitization ------------------------------------ #
 
 # Substrings (case-insensitive) of keys that must never reach a span: secrets,