Python: feature: Inject OpenTelemetry trace context into MCP requests and update…

[peteroden]

Motivation and Context

When an Agent Framework application calls tools on remote MCP servers, the OpenTelemetry trace context is lost at the MCP transport boundary. The agent's span tree stops at call_tool() and the MCP server starts a new, unrelated trace — breaking distributed tracing and preventing end-to-end latency visibility across agent → MCP server calls.

The MCP specification (2025-11-25) reserves params._meta for exactly this kind of client/server metadata: "The _meta property/parameter is reserved by MCP to allow clients and servers to attach additional metadata to their interactions."

Fixes #3778

Description

Adds a _inject_otel_into_mcp_meta() helper that uses opentelemetry.propagate.inject() to write the current trace context into a carrier dict, then merges it into the MCP request _meta. This is wired into MCPTool.call_tool() — the single chokepoint for all transports (stdio, SSE, streamable HTTP).

Key design decisions:

• Propagator-agnostic: forwards whatever keys the configured propagator(s) produce (W3C traceparent/tracestate, B3, etc.) rather than hardcoding specific headers
• Optional dependency: OpenTelemetry import is guarded by try/except ImportError so the framework works unchanged when OTel is not installed
• Merge-not-clobber: never overwrites existing _meta keys
• No gate on OBSERVABILITY_SETTINGS: propagation happens whenever a valid span context exists, independent of the framework's observability configuration

Files changed:

• packages/core/agent_framework/_mcp.py — added _inject_otel_into_mcp_meta() helper, wired into MCPTool.call_tool()
• packages/core/tests/core/test_mcp.py — added parametrized test covering span/no-span cases
• samples/getting_started/observability/README.md — added MCP trace propagation documentation note

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? No — this is additive behavior with no API changes.

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_mcp.py	416	63	84%	97–98, 108–113, 124, 129, 175–176, 186–191, 201–202, 254, 263, 326, 334, 485, 552, 587, 589, 593–594, 596–597, 651, 666, 684, 725, 830, 843–848, 870, 919–920, 926–928, 947, 972–973, 977–981, 998–1002, 1146
TOTAL	20576	3227	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
3957	225 💤	0 ❌	0 🔥	1m 10s ⏱️

[Copilot]

Pull request overview

Adds OpenTelemetry trace-context propagation across the MCP transport boundary by injecting the active trace context into MCP tools/call requests via params._meta, enabling end-to-end distributed tracing from Agent Framework → MCP servers.

Changes:

• Add _inject_otel_into_mcp_meta() helper to inject the current OTel context into an MCP _meta carrier.
• Wire OTel meta injection into MCPTool.call_tool() so all MCP transports benefit.
• Add a unit test and a documentation note describing MCP trace propagation.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
python/packages/core/agent_framework/_mcp.py	Injects OTel propagation fields into MCP tool calls via the request meta field.
python/packages/core/tests/core/test_mcp.py	Adds a test validating meta injection behavior for active vs inactive span contexts.
python/samples/getting_started/observability/README.md	Documents that trace context is propagated to MCP servers using params._meta.

[peteroden]

@copilot open a new pull request to apply changes based on the comments in this thread

[peteroden]

@rogerbarreto and @markwallace-microsoft, are any additional changes needed to get this merged? Happy to make any edits needed. There are a few projects in flight that this update would really help with. I am not able to rerun the markdown-lint-check for some reason. Perhaps permissions?

[cicorias]

@rogerbarreto and @markwallace-microsoft, are any additional changes needed to get this merged? Happy to make any edits needed. There are a few projects in flight that this update would really help with. I am not able to rerun the markdown-lint-check for some reason. Perhaps permissions?

yes -- we are too awaiting this for active work as well. @rogerbarreto @markwallace-microsoft