Add MCP semantic conventions to otelv2

[yassin-berriai]

Relevant issues

otelv2 had no semantic conventions for MCP (Model Context Protocol), so MCP tool calls flowed through the proxy without ever producing a span. This adds support following the OpenTelemetry GenAI MCP semconv: https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/

Linear ticket

Resolves LIT-3509

What changed

A closed call_mcp_tool request now emits a CLIENT span named tools/call {tool}. The proxy is an MCP client to the upstream server it dispatches the tool to, so the span is a sibling of the LLM-call span under the request's server span. It carries mcp.method.name, gen_ai.operation.name=execute_tool, gen_ai.tool.name, mcp.session.id (for stateful MCP sessions), the upstream server name (litellm.mcp.server.name, a vendor key since semconv has no name attribute for an MCP server), the litellm call id, and cost. The tool arguments and result (gen_ai.tool.call.arguments / gen_ai.tool.call.result) are sensitive content, so they are opt-in and gated by the same content-capture mode as prompt/response bodies. Failures set the span status to ERROR with error.type.

The work is split across the three existing sources of truth so nothing is special-cased in the engine. The semconv module gains the full MCP attribute vocabulary (the mcp.*, jsonrpc.* / rpc.*, network.*, and client.* keys, plus gen_ai.tool.call.* and gen_ai.prompt.name), an MCPMethod enum, and a call_mcp_tool operation mapping; payloads.py gains an MCPToolCallSpanData built from StandardLoggingMCPToolCall; spans.py gains the MCP_TOOL_CALL role and its name builder; the canonical GenAI mapper learns the new span type; and the v2 logger detects an MCP payload in its success/failure callbacks and emits the span there (these calls have no pre_call carrier, so the whole span is emitted at once and deduped on the call id).

To populate mcp.session.id, the gateway now captures the mcp-session-id header at the tool-call entry point and threads it through StandardLoggingMCPToolCall; stateless calls have no such header and the attribute is simply absent.

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all unit tests
• My PR's scope is as isolated as possible; it only solves 1 specific problem

Type

🆕 New Feature

Changes

Span emission and the MCP/JSON-RPC vocabulary live within litellm/integrations/otel; the only proxy change is capturing the session-id header into the tool-call logging metadata. Tests cover the semconv operation resolution, the full attribute vocabulary, the typed adapter (field extraction including session id, content gating, failure path, MCP detection), the span name, the case-insensitive session-id header read, and the end-to-end logger flow (CLIENT span with the right attributes including mcp.session.id, content gated off by default and captured when enabled, error status on failure, dedup on repeat callbacks, and that an MCP call is never recorded as an LLM chat span).

https://claude.ai/code/session_015H6D6QD31QCw3omAPksSm8

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds OTel GenAI MCP semantic conventions to the otelv2 integration, emitting a CLIENT span named tools/call {tool} for each call_mcp_tool request. The implementation follows the three-source-of-truth pattern already established in the codebase (semconv vocab, typed adapter, span role + name builder), adds content-gating for sensitive tool I/O, and populates mcp.session.id from the mcp-session-id HTTP header.

• semconv.py gains the full MCP/JSON-RPC/Network/Client attribute vocabulary and MCPMethod enum; payloads.py adds MCPToolCallSpanData and is_mcp_tool_call; spans.py and mappers/genai.py register the new span role and its attribute map.
• logger.py adds _emit_mcp_tool_call, which short-circuits the LLM-call path in the async success/failure callbacks and emits the MCP span; server.py captures the session-id header and threads it through StandardLoggingMCPToolCall.
• Tests cover semconv vocabulary completeness, operation resolution, adapter field extraction, content gating, span naming, header case-insensitivity, and the end-to-end logger flow (CLIENT kind, attribute values, dedup, error status).

Confidence Score: 3/5

Safe to merge with one functional gap: MCP spans will not be exported to per-tenant OTel endpoints even when the tenant has configured a custom standard_callback_dynamic_params endpoint, unlike LLM spans which already respect it.

The core implementation is well-structured and follows existing patterns, and the test suite is thorough on the happy path. The missing per-tenant tracer argument in _emit_mcp_tool_call means that for any deployment using dynamic per-tenant OTel routing, MCP tool-call spans will silently go to the wrong exporter while LLM spans go to the correct one. This is a present behavioral difference on a real code path, not a speculative future issue.

litellm/integrations/otel/logger.py — the _emit_mcp_tool_call method needs a tracer argument wired through _tenant_tracers.tracer_for the same way _close_llm_call does at line 314.

Important Files Changed

Filename	Overview
litellm/integrations/otel/logger.py	Adds _emit_mcp_tool_call to detect and emit MCP CLIENT spans; per-tenant OTel routing is missing (no tracer argument passed to emit).
litellm/integrations/otel/model/payloads.py	Adds MCPToolCallSpanData and is_mcp_tool_call; method field is always hardcoded to tools/call regardless of actual call type.
litellm/integrations/otel/model/semconv.py	Adds full MCP/JSON-RPC/Network/Client semconv vocabulary and MCPMethod enum; adds call_mcp_tool to operation map. Clean and well-documented.
litellm/integrations/otel/model/spans.py	Adds MCP_TOOL_CALL span role as a CLIENT span sibling of LLM_CALL under PROXY_REQUEST, and mcp_tool_call_span_name builder.
litellm/integrations/otel/mappers/genai.py	Adds _MCP_ATTRS dictionary and routes MCPToolCallSpanData through it in map(); attribute set is complete and consistent with semconv.
litellm/proxy/_experimental/mcp_server/server.py	Adds _mcp_session_id_from_headers (case-insensitive header read) and threads session_id through _get_standard_logging_mcp_tool_call; clean change.
litellm/integrations/otel/emitter.py	Extends dedup key and error-handling isinstance checks to include MCPToolCallSpanData; straightforward and correct.
litellm/types/utils.py	Adds optional mcp_session_id field to StandardLoggingMCPToolCall; backwards-compatible TypedDict extension.
tests/test_litellm/integrations/otel/test_otel_v2_logger.py	Good coverage for MCP spans (CLIENT kind, attributes, content gating, dedup, error path); stray-carrier cleanup path is not actually exercised despite the test claiming it is.
tests/test_litellm/integrations/otel/test_otel_v2_sources_of_truth.py	Thorough semconv vocabulary coverage, operation resolution, adapter field extraction, content gating, and span name tests; clean additions with no weakened assertions.
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_session_logging.py	New test file covering case-insensitive header reading and stateless/absent session-id cases; no real network calls.

Comments Outside Diff (2)

1. litellm/integrations/otel/logger.py, line 202-209 (link)

   MCP spans skip per-tenant OTel routing

   _emit_mcp_tool_call calls self._emitter.emit(...) without a tracer argument, so MCP tool-call spans are always exported to the default OTLP endpoint. Compare with _close_llm_call at line 314, which passes tracer=self._tenant_tracers.tracer_for(self.tracer, call.dynamic_params). Any tenant that configures a custom OTel endpoint via standard_callback_dynamic_params will have their MCP spans silently routed to the wrong (shared) exporter while their LLM spans go to the correct tenant-specific one. kwargs.get("standard_callback_dynamic_params") is available in this method and could be threaded the same way.

2. tests/test_litellm/integrations/otel/test_otel_v2_logger.py, line 704-714 (link)

   Test doesn't actually exercise the stray-carrier cleanup path it describes

   The docstring says "even if pre_call opened a stray carrier for this id" but log_pre_api_call returns early on line 175–176 because kwargs has no top-level litellm_call_id key (call_id is None). No carrier is ever inserted into _open_llm_calls, so the cleanup line self._open_llm_calls.pop(data.identity.call_id, None) is never reached. To actually guard the described scenario, the test should seed _open_llm_calls directly with a fake carrier keyed on "mcp_1" and assert it is absent after the success callback fires.

_{Reviews (1): Last reviewed commit: "Test that stateless MCP calls omit mcp.s..." | Re-trigger Greptile}

[greptile-apps]

method is always hardcoded to tools/call

MCPMethod.TOOLS_CALL.value is stamped regardless of the actual call type, making the other three MCPMethod enum values (TOOLS_LIST, PROMPTS_GET, PROMPTS_LIST) unreachable from this adapter. If a future MCP operation is added that goes through the same from_standard_logging_payload path, its spans will silently claim mcp.method.name = "tools/call" instead of the correct wire name. A comment here clarifying the deliberate assumption ("currently all spans from this factory originate from call_mcp_tool") would prevent a copy-paste error when the next operation is added.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!