opentelemetry-util-genai: add MCP invocation types and TelemetryHandler support

[etserend]

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-in

Tool 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

1. Semconv constants: mcp.* and jsonrpc.* attributes are not yet in the opentelemetry-semantic-conventions Python package. The established pattern (see _GEN_AI_AGENT_VERSION in _agent_invocation.py) is module-level string literals with a # TODO: Migrate once in semconv package comment. Is that acceptable here?

2. Session duration: mcp.client/server.session.duration should be recorded when the session ends. Should the invocation type detect mcp_method_name == "initialize" and record session duration automatically on stop(), or should this be caller-driven via metric_attributes?

3. mcp.resource.uri on 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 via metric_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.name enum — 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.

[YuxiangJiangCT]

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:

1. 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?

2. The MCP semconv is still Development. Do you want to pin to 243e57b and bump deliberately, or track semantic-conventions-genai main as it moves?

3. On your maintainer Q3 (mcp.resource.uri on metrics): a typed include_resource_uri_in_metrics flag reads as more discoverable and keeps the opt-in explicit, versus relying on callers to pass the right metric_attributes key.

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]

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:

1. 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?
2. The MCP semconv is still Development. Do you want to pin to 243e57b and bump deliberately, or track semantic-conventions-genai main as it moves?
3. On your maintainer Q3 (mcp.resource.uri on metrics): a typed include_resource_uri_in_metrics flag reads as more discoverable and keeps the opt-in explicit, versus relying on callers to pass the right metric_attributes key.

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.

@YuxiangJiangCT thanks for your review and time. Currently, I'm holding off this PR due to opening PR against MCP Python SDK.