Repository navigation
Description
What problem do you want to solve?
opentelemetry-util-genai provides reusable invocation types (ToolInvocation, AgentInvocation, WorkflowInvocation, etc.) and a TelemetryHandler with lifecycle methods and context managers for each. There is currently no equivalent for Model Context Protocol (MCP) operations.
The GenAI semconv MCP spec (status: Development, merged January 2026) defines two canonical span types — mcp.client (SpanKind: CLIENT) and mcp.server (SpanKind: SERVER) — along with four metrics histograms. Without MCP types in opentelemetry-util-genai, each MCP SDK instrumentation must independently re-implement the same span and metric plumbing, risking drift from the semconv.
This was observed in practice: issue #4197 reported MCP list-tools spans showing as "unknown" in opentelemetry-instrumentation-openai-agents-v2, and PR #4629 added a per-instrumentation workaround rather than building on a shared foundation.
Describe the solution you'd like
Add MCPClientInvocation and MCPServerInvocation types to opentelemetry-util-genai, with lifecycle methods and context managers on TelemetryHandler, and four MCP-specific metric histograms.
MCPClientInvocation — covers all MCP operations initiated by the client side (mcp.client span type, SpanKind.CLIENT):
invocation = handler.start_mcp_client(
mcp_method_name="tools/call",
tool_name="get_weather",
server_address="mcp.example.com",
server_port=443,
)
invocation.mcp_session_id = "..."
invocation.mcp_protocol_version = "2025-06-18"
invocation.jsonrpc_request_id = "1"
invocation.tool_call_arguments = {...} # opt-in
invocation.stop()
# context manager form
with handler.mcp_client(mcp_method_name="resources/read", mcp_resource_uri="file:///report.pdf") as inv:
inv.mcp_session_id = "..."MCPServerInvocation — covers all MCP operations processed on the server side (mcp.server span type, SpanKind.SERVER):
with handler.mcp_server(mcp_method_name="tools/call", tool_name="get_weather") as inv:
inv.client_address = "192.0.2.1"
inv.tool_call_result = {...} # opt-inTool call operations (mcp.method.name = "tools/call") are handled by the same MCPClientInvocation / MCPServerInvocation types — the spec explicitly states that mcp.client/mcp.server spans with tools/call are compatible with GenAI execute_tool spans. The invocation type automatically sets gen_ai.operation.name = execute_tool when mcp_method_name == "tools/call", and SHOULD NOT set it for any other method.
Span name follows {mcp.method.name} {target} where target is gen_ai.tool.name or gen_ai.prompt.name when applicable; plain {mcp.method.name} otherwise.
Attributes (from spans.yaml and common.yaml):
| Attribute | Requirement level | Client | Server |
|---|---|---|---|
mcp.method.name |
Required | ✅ | ✅ |
gen_ai.tool.name |
Cond. req. when tool op | ✅ | ✅ |
gen_ai.operation.name |
Recommended (execute_tool for tools/call only) |
✅ | ✅ |
gen_ai.prompt.name |
Cond. req. when prompt op | ✅ | ✅ |
error.type |
Cond. req. on error | ✅ | ✅ |
mcp.protocol.version |
Recommended | ✅ | ✅ |
rpc.response.status_code |
Cond. req. | ✅ | ✅ |
mcp.session.id |
Recommended | ✅ | ✅ |
mcp.resource.uri |
Cond. req. for resource ops | ✅ | ✅ |
jsonrpc.request.id |
Cond. req. | ✅ | ✅ |
network.transport / network.protocol.* |
Recommended | ✅ | ✅ |
jsonrpc.protocol.version |
Recommended (when ≠ 2.0) |
✅ | ✅ |
server.address / server.port |
Recommended | ✅ | — |
client.address / client.port |
Recommended | — | ✅ |
gen_ai.tool.call.arguments |
Opt-in | ✅ | ✅ |
gen_ai.tool.call.result |
Opt-in | ✅ | ✅ |
TelemetryHandler additions:
def start_mcp_client(self, *, mcp_method_name: str, tool_name=None, prompt_name=None,
server_address=None, server_port=None) -> MCPClientInvocation: ...
def mcp_client(self, *, mcp_method_name: str, ...) -> AbstractContextManager[MCPClientInvocation]: ...
def start_mcp_server(self, *, mcp_method_name: str, tool_name=None, prompt_name=None,
client_address=None, client_port=None) -> MCPServerInvocation: ...
def mcp_server(self, *, mcp_method_name: str, ...) -> AbstractContextManager[MCPServerInvocation]: ...Metrics (from metrics.yaml):
| Metric | Unit | Notes |
|---|---|---|
mcp.client.operation.duration |
s |
All client-side MCP operations |
mcp.server.operation.duration |
s |
All server-side MCP operations |
mcp.client.session.duration |
s |
Recorded on initialize completion |
mcp.server.session.duration |
s |
Recorded on initialize completion |
InvocationMetricsRecorder extended with four new histograms in instruments.py. mcp.resource.uri included as opt-in metric dimension per spec.
Exports: MCPClientInvocation and MCPServerInvocation added to invocation.py __all__.
Questions for maintainers
-
Semconv constants:
mcp.*andjsonrpc.*attributes are not yet in theopentelemetry-semantic-conventionsPython package. The established pattern (see_GEN_AI_AGENT_VERSIONin_agent_invocation.py) is module-level string literals with a# TODO: Migrate once in semconv packagecomment. Is that acceptable here? -
Session duration:
mcp.client/server.session.durationshould be recorded when the session ends. Should the invocation type detectmcp_method_name == "initialize"and record session duration automatically onstop(), or should this be caller-driven viametric_attributes? -
mcp.resource.urion metrics: Spec marks it as opt-in for operation duration. Should this be a flag on the invocation (e.g.include_resource_uri_in_metrics: bool = False) or left to the caller viametric_attributes?
References
- Semconv spans:
model/mcp/spans.yaml - Semconv common attrs:
model/mcp/common.yaml - Semconv metrics:
model/mcp/metrics.yaml - Semconv registry (
mcp.method.nameenum — 27 values):model/mcp/registry.yaml - Related bug: [OpenAI Agents] MCP List Tools spans show only as "unknown" with no data #4197
- Related workaround: opentelemetry-instrumentation-openai-agents-v2: handle MCPListToolsSpanData #4629
Would you like to implement this?
Yes — we plan to open a PR once we have alignment on the questions above.
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity
YuxiangJiangCT commentedon Jun 15, 2026
This would be valuable. Each MCP instrumentation currently re-implements the same span/metric plumbing and drifts from semconv, and the #4197 / #4629 case you cited is a clear symptom.
A couple of scoping questions, plus a thought on one of your open questions:
One PR or staged? It splits cleanly into (a)
MCPClientInvocation+start_mcp_client/mcp_client, (b)MCPServerInvocation+ the server-side methods, (c) the four histograms. Would you want (a) to land first to keep the initial review tractable, or land it together?The MCP semconv is still Development. Do you want to pin to
243e57band bump deliberately, or track semantic-conventions-genaimainas it moves?On your maintainer Q3 (
mcp.resource.urion metrics): a typedinclude_resource_uri_in_metricsflag reads as more discoverable and keeps the opt-in explicit, versus relying on callers to pass the rightmetric_attributeskey.Glad to help if it's useful — I could take a piece like (a) or pair on it, whichever fits how you want to drive this.
etserend commentedon Jun 16, 2026
@YuxiangJiangCT thanks for your review and time. Currently, I'm holding off this PR due to opening PR against MCP Python SDK.