Server spans lose HTTP parent when MCP trace context is also present (dual-parent / link scenario)

[strawgate]

When FastMCP runs behind an OTEL-instrumented HTTP framework (e.g. Starlette, FastAPI with opentelemetry-instrumentation-starlette), each incoming HTTP request creates an HTTP span. If the MCP client also propagates a traceparent in _meta, the server-side MCP operation span has two candidate parents:

1. The ambient HTTP request span from the outer transport layer
2. The MCP traceparent from the MCP client's trace

A span can only have one parent. Today FastMCP uses the MCP _meta context as the parent (correct for end-to-end MCP traces). This means the ambient HTTP span is silently dropped from the span hierarchy.

The spec-correct approach

OpenTelemetry's Links are designed for exactly this fan-in pattern (also used for Kafka consumers, pub/sub, batch jobs, etc.). The right model is:

• Parent: MCP traceparent from _meta (the MCP client owns the logical trace)
• Link: ambient HTTP request span (the transport context is preserved but not the primary trace)

What was implemented in PR #4046

The PR stored the ambient HTTP span context in the ASGI scope during request dispatch:

# In StreamableHTTPASGIApp.__call__:
ambient_span_context = trace.get_current_span().get_span_context()
if ambient_span_context.is_valid:
    scope[AMBIENT_SPAN_CONTEXT_SCOPE_KEY] = ambient_span_context

Then in _get_parent_trace_context() it checked whether the resolved MCP parent differed from the ambient HTTP span and, if so, recorded the HTTP span as a Link:

if ambient_span_context.is_valid and parent_span_context != ambient_span_context:
    return parent_context, [Link(ambient_span_context)]

Why it was deferred

This scenario only arises when all three conditions are simultaneously true:

1. HTTP transport (not stdio)
2. Another OTEL-instrumented framework wrapping FastMCP
3. MCP client is also propagating trace context in _meta

The implementation added meaningful complexity (ASGI scope plumbing, a new constant, changes to _get_parent_trace_context signature) for a fairly narrow edge case. We removed it from PR #4046 to keep the initial interop feature minimal.

When to revisit

This is worth implementing when there is concrete user demand — e.g. someone running FastMCP mounted in a FastAPI app with starlette-instrumentation and distributed tracing active. At that point the Link approach is the right solution and the implementation in PR #4046 is a reasonable starting point.

Related

• PR feat: Add telemetry interop mode for FastMCP #4046 (telemetry interop mode) — removed this implementation

[marvin-context-protocol]

Claude finished @strawgate's task in 6m 27s —— View job

---

tl;dr: Valid enhancement request. The issue is well-specified and the implementation approach (OTel Links) is spec-correct. The current code at extract_trace_context has a related subtlety worth noting: it actively prefers the ambient HTTP span over MCP _meta when both are in the same OTel context, but in practice the ambient HTTP span likely doesn't survive into the MCP handler task anyway. The fix involves 3 files and is moderate complexity.

Recommendation: Implement as described — capture the ambient HTTP span context in StreamableHTTPASGIApp.__call__, pass it through the ASGI scope, and attach it as an OTel Link in server_span. This should be gated behind the same conditions the issue outlines (ambient span present + MCP _meta parent differs from it). This can be done independently of PR #4046 (telemetry interop mode).

Findings

Current behavior of extract_trace_context

The function at fastmcp_slim/fastmcp/telemetry.py:82-111 has a guard at lines 95-98:

# Don't override existing trace context (e.g., from HTTP propagation)
current_span = trace.get_current_span()
if current_span.get_span_context().is_valid:
    return otel_context.get_current()

This means: if there's a valid span already in the OTel context when extract_trace_context runs, the MCP _meta traceparent is silently ignored. In theory this makes the HTTP span the parent.

However, in practice this guard likely never fires in the dual-parent scenario. The MCP SDK's StreamableHTTPSessionManager processes requests in background tasks (anyio task groups), and Python's contextvars — which underpin opentelemetry.context — don't automatically propagate OTel span context across task boundaries unless explicitly copied. So by the time _get_parent_trace_context() runs inside the MCP handler, the ambient HTTP span from Starlette instrumentation is no longer the "current span." The MCP _meta traceparent is used as parent, and the HTTP span is effectively orphaned.

This is what the issue describes: the server operation span correctly parents under the MCP trace, but the HTTP transport span has no child relationship to it — it's silently dropped from the hierarchy.

Where the ambient span exists

The ambient HTTP span is active in StreamableHTTPASGIApp.__call__ (fastmcp_slim/fastmcp/server/http.py:38-65), since Starlette instrumentation wraps the ASGI call. This is where it needs to be captured before it's lost to task boundaries.

_get_parent_trace_context and server_span

_get_parent_trace_context() at fastmcp_slim/fastmcp/server/telemetry.py:45-53 currently returns Context | None. It needs to also return optional Link objects.

server_span() at fastmcp_slim/fastmcp/server/telemetry.py:56-105 calls tracer.start_as_current_span(name, context=..., kind=SpanKind.SERVER). The start_as_current_span API accepts a links parameter — this is where the ambient HTTP span would be attached as a Link.

Relationship to PR #4046

PR #4046 (still open) adds a propagation_only telemetry mode to suppress FastMCP's native spans. The Link implementation was stripped from that PR to keep scope narrow. These two features are orthogonal:

• feat: Add telemetry interop mode for FastMCP #4046: suppress FastMCP spans when another instrumentation layer owns MCP spans
• This issue: preserve the HTTP transport span as a Link when MCP _meta owns the parent

They can be implemented independently without conflicts.

Detailed Action Plan

Step 1: Capture ambient span in ASGI scope

File: fastmcp_slim/fastmcp/server/http.py

Add a module-level constant and capture logic in StreamableHTTPASGIApp.__call__:

from opentelemetry import trace

AMBIENT_SPAN_CONTEXT_SCOPE_KEY = "fastmcp.ambient_span_context"

class StreamableHTTPASGIApp:
    async def __call__(self, scope, receive, send):
        # Capture ambient span before it's lost to task boundaries
        ambient_span_context = trace.get_current_span().get_span_context()
        if ambient_span_context.is_valid:
            scope[AMBIENT_SPAN_CONTEXT_SCOPE_KEY] = ambient_span_context
        # ... existing code

Step 2: Thread ambient span context to _get_parent_trace_context

File: fastmcp_slim/fastmcp/server/telemetry.py

The ambient span context needs to reach _get_parent_trace_context. Since the ASGI scope is available in the request flow but not directly in the telemetry module, there are two options:

Option A (ContextVar): Store the ambient span context in a ContextVar set by middleware/ASGI app, then read it in _get_parent_trace_context. This avoids plumbing the scope through multiple layers.

Option B (ASGI scope plumbing): Pass it through from the ASGI scope to the MCP handler. This is more explicit but requires changes to how the scope is accessed.

Option A is simpler:

# In http.py
from contextvars import ContextVar
_ambient_span_context: ContextVar[SpanContext | None] = ContextVar(
    "ambient_span_context", default=None
)

# Set in StreamableHTTPASGIApp.__call__ or RequestContextMiddleware

Step 3: Update _get_parent_trace_context return type

File: fastmcp_slim/fastmcp/server/telemetry.py

from opentelemetry.trace import Link, SpanContext

def _get_parent_trace_context() -> tuple[Context | None, list[Link]]:
    links: list[Link] = []
    parent_context = None
    try:
        req_ctx = request_ctx.get()
        if req_ctx and hasattr(req_ctx, "meta") and req_ctx.meta:
            parent_context = extract_trace_context(dict(req_ctx.meta))
    except LookupError:
        pass

    # If MCP _meta provided a parent AND ambient HTTP span exists and differs,
    # record the HTTP span as a Link
    ambient = _ambient_span_context.get()
    if ambient is not None and ambient.is_valid:
        parent_span_context = (
            trace.get_current_span(parent_context).get_span_context()
            if parent_context else None
        )
        if parent_span_context and parent_span_context != ambient:
            links.append(Link(ambient))

    return parent_context, links

Step 4: Pass links to server_span

File: fastmcp_slim/fastmcp/server/telemetry.py

def server_span(...) -> Generator[Span, None, None]:
    tracer = get_tracer()
    parent_context, links = _get_parent_trace_context()
    with tracer.start_as_current_span(
        name,
        context=parent_context,
        kind=SpanKind.SERVER,
        links=links or None,
    ) as span:
        # ... existing attribute/error logic

Step 5: Update extract_trace_context guard

File: fastmcp_slim/fastmcp/telemetry.py

The guard at lines 95-98 that prefers the ambient HTTP span should be reconsidered. When MCP _meta is present, it should be the parent (not the ambient HTTP span). The guard should either be removed or changed to only apply when no _meta traceparent is present. This is the key behavioral change — it ensures MCP _meta always wins as the parent.

Step 6: Add tests

File: tests/telemetry/test_module.py or new tests/telemetry/test_links.py

• Test that when both ambient HTTP span and MCP _meta exist, MCP _meta is the parent
• Test that the ambient HTTP span appears as a Link on the server span
• Test that when only MCP _meta exists, no links are added
• Test that when only ambient HTTP span exists (no MCP _meta), the HTTP span is the parent with no links

Step 7: Update docs

File: docs/servers/telemetry.mdx

Add a section explaining the Link behavior for the dual-parent scenario.

Related Issues and Pull Requests

Issue or PR	Relevance
#4046 — feat: Add telemetry interop mode for FastMCP	The Link implementation was originally part of this PR but was removed to keep scope narrow. Still open. Adds propagation_only telemetry mode, orthogonal to this issue.

Related Files

File	Relevance
fastmcp_slim/fastmcp/telemetry.py L82-111	extract_trace_context — contains the guard at L95-98 that prefers ambient HTTP span over MCP _meta. Key behavioral change needed here.
fastmcp_slim/fastmcp/server/telemetry.py L45-53	_get_parent_trace_context — needs to return Links alongside the parent context
fastmcp_slim/fastmcp/server/telemetry.py L56-105	server_span — needs to pass links to start_as_current_span
fastmcp_slim/fastmcp/server/http.py L32-65	StreamableHTTPASGIApp.__call__ — where ambient HTTP span context must be captured before task boundary
tests/telemetry/test_module.py	Existing trace context tests — new Link tests should follow these patterns

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[kephale]

Happy to pick this up — the Link approach aligns with how OTel treats Kafka/pub-sub fan-in (semconv trace/links) and matches what other MCP-adjacent runtimes are converging on. Before I open a PR, two design questions:

1. The extract_trace_context guard at fastmcp_slim/fastmcp/telemetry.py:95-98 currently returns early if a valid span is already in the OTel context, which means an ambient HTTP span beats MCP _meta when both are visible at extraction time. The bot comment correctly notes this rarely fires today because the MCP SDK's StreamableHTTPSessionManager dispatches to an anyio task group and contextvars don't cross task boundaries unless explicitly copied. But that's load-bearing implementation detail — if the SDK ever copies context (which would actually be more correct), the guard would silently invert the priority you want. I'd prefer to remove or invert it in the same PR so the priority is explicit: MCP _meta always wins as parent, ambient HTTP span goes on Link. Reasonable?

2. Link attributes. The OTel GenAI semconv (v1.37) doesn't yet define link attributes for the dual-parent case, but mcp.transport and network.protocol.name are stable. I'd plan to attach {"mcp.link.kind": "http_transport"} to the Link so consumers can filter, with a note in docs/servers/telemetry.mdx. Open to a different attribute key if there's a convention already in use elsewhere in the codebase.

Implementation plan: capture trace.get_current_span().get_span_context() in StreamableHTTPASGIApp.__call__ into a module-level ContextVar (Option A from the bot comment — avoids ASGI scope plumbing), surface it through _get_parent_trace_context() -> tuple[Context | None, list[Link]], and pass links= into tracer.start_as_current_span inside server_span(). Tests under tests/telemetry/ covering: dual-parent (MCP wins, HTTP linked), MCP-only (no link), HTTP-only (HTTP is parent, no link), and stdio (no ambient span, no link). Aiming for the PR to be reviewable independently of #4046.

If that's the right shape I'll have a draft up this week.