Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(telemetry): record mounted and nested server spans as INTERNAL (#6252)

nate nowack15de7f090134
diff --git a/docs/servers/telemetry.mdx b/docs/servers/telemetry.mdx
index 030606899..bd5d9e544 100644
--- a/docs/servers/telemetry.mdx
+++ b/docs/servers/telemetry.mdx
@@ -147,9 +147,11 @@ Spans form a hierarchy showing the request flow. For mounted servers:
tools/call weather_forecast (CLIENT)
└── tools/call weather_forecast (SERVER, provider=FastMCPProvider)
└── delegate get_weather (INTERNAL)
- └── tools/call get_weather (SERVER, provider=LocalProvider)
+ └── tools/call get_weather (INTERNAL, provider=LocalProvider)
```
+Each request has exactly one `SERVER` span. The mounted server's span is `INTERNAL`, as is the span for a tool that calls another tool through `ctx.fastmcp.call_tool()`, so trace backends that count `SERVER` spans as requests count each call once.
+
For proxy providers connecting to remote servers:
```
diff --git a/fastmcp_slim/fastmcp/server/telemetry.py b/fastmcp_slim/fastmcp/server/telemetry.py
index 4d073d45b..1226cda64 100644
--- a/fastmcp_slim/fastmcp/server/telemetry.py
+++ b/fastmcp_slim/fastmcp/server/telemetry.py
@@ -39,6 +39,14 @@ _active_seam_span: ContextVar[Span | None] = ContextVar(
"fastmcp_active_seam_span", default=None
)
+# Set once `server_span` has claimed the request's SERVER span. A mounted
+# server, or a tool calling `ctx.fastmcp.call_tool`, reaches `server_span`
+# again inside that request; it records an INTERNAL span instead, so trace
+# consumers see one request no matter how deep the call goes.
+_server_span_open: ContextVar[bool] = ContextVar(
+ "fastmcp_server_span_open", default=False
+)
+
def get_auth_span_attributes() -> dict[str, str]:
"""Get auth attributes for the current request, if authenticated."""
@@ -211,12 +219,16 @@ def seam_span(method: str, server_name: str) -> Generator[Span, None, None]:
if span.is_recording():
restore_dropped_attributes(span, attrs)
token = _active_seam_span.set(span)
+ # A seam is a new inbound request, even one an in-process proxy sends
+ # from inside another server's tool call.
+ open_token = _server_span_open.set(False)
try:
yield span
except Exception as e:
record_span_exception(span, e)
raise
finally:
+ _server_span_open.reset(open_token)
_active_seam_span.reset(token)
@@ -241,6 +253,10 @@ def server_span(
e.g. in-process `mcp.call_tool()` calls that bypass the dispatcher) it opens a
new SERVER span as before.
+ A call nested inside that span, through a mounted server or a tool calling
+ `ctx.fastmcp.call_tool`, gets an INTERNAL span under the current one, so a
+ request has exactly one SERVER span.
+
Automatically records any exception on the span and sets error status.
In `propagation_only` mode no span is opened or enriched. The seam has
@@ -263,6 +279,19 @@ def server_span(
prompt_name,
)
+ if _server_span_open.get():
+ with get_tracer().start_as_current_span(
+ name, kind=SpanKind.INTERNAL, attributes=attrs
+ ) as span:
+ if span.is_recording():
+ restore_dropped_attributes(span, attrs)
+ try:
+ yield span
+ except Exception as e:
+ record_span_exception(span, e)
+ raise
+ return
+
seam = _active_seam_span.get()
active = get_current_span()
if (
@@ -274,11 +303,14 @@ def server_span(
# Enrich the already-active seam span rather than opening a second one.
seam.update_name(name)
seam.set_attributes(attrs)
+ token = _server_span_open.set(True)
try:
yield seam
except Exception as e:
record_span_exception(seam, e)
raise
+ finally:
+ _server_span_open.reset(token)
return
tracer = get_tracer()
@@ -294,11 +326,14 @@ def server_span(
# fires when the span ends up with no attributes at all.
if span.is_recording():
restore_dropped_attributes(span, attrs)
+ token = _server_span_open.set(True)
try:
yield span
except Exception as e:
record_span_exception(span, e)
raise
+ finally:
+ _server_span_open.reset(token)
@contextmanager
diff --git a/tests/server/telemetry/test_provider_tracing.py b/tests/server/telemetry/test_provider_tracing.py
index 50c33f8fe..f766baef7 100644
--- a/tests/server/telemetry/test_provider_tracing.py
+++ b/tests/server/telemetry/test_provider_tracing.py
@@ -3,6 +3,7 @@
from __future__ import annotations
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+from opentelemetry.trace import SpanKind
from fastmcp import Client, Context, FastMCP
from fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient
@@ -183,3 +184,101 @@ class TestModernProxyTracePropagation:
assert TRACE_PARENT_KEY in seen["resource"]
assert TRACE_PARENT_KEY in seen["template"]
assert TRACE_PARENT_KEY in seen["prompt"]
+
+
+class TestOneServerSpanPerRequest:
+ """A request crosses one server boundary, however deep the mounts go."""
+
+ @staticmethod
+ def _server_spans(exporter: InMemorySpanExporter) -> list:
+ return [
+ s
+ for s in exporter.get_finished_spans()
+ if s.kind == SpanKind.SERVER
+ and s.attributes is not None
+ and s.attributes.get("mcp.method.name") == "tools/call"
+ ]
+
+ async def test_mounted_call_over_a_client(
+ self, trace_exporter: InMemorySpanExporter
+ ):
+ child = FastMCP("child")
+
+ @child.tool
+ def hello() -> str:
+ return "world"
+
+ parent = FastMCP("parent")
+ parent.mount(child, namespace="sub")
+
+ async with Client(parent) as client:
+ await client.call_tool("sub_hello", {})
+
+ spans = trace_exporter.get_finished_spans()
+ (server,) = self._server_spans(trace_exporter)
+ assert server.name == "tools/call sub_hello"
+ delegate = next(s for s in spans if s.name == "delegate hello")
+ child_span = next(s for s in spans if s.name == "tools/call hello")
+ assert child_span.kind == SpanKind.INTERNAL
+ assert child_span.parent is not None
+ assert child_span.parent.span_id == delegate.context.span_id
+
+ async def test_nested_mounts_in_process(self, trace_exporter: InMemorySpanExporter):
+ leaf = FastMCP("leaf")
+
+ @leaf.tool
+ def hello() -> str:
+ return "world"
+
+ middle = FastMCP("middle")
+ middle.mount(leaf, namespace="leaf")
+ root = FastMCP("root")
+ root.mount(middle, namespace="mid")
+
+ await root.call_tool("mid_leaf_hello", {})
+
+ (server,) = self._server_spans(trace_exporter)
+ assert server.name == "tools/call mid_leaf_hello"
+
+ async def test_tool_calling_a_tool(self, trace_exporter: InMemorySpanExporter):
+ mcp = FastMCP("nested")
+
+ @mcp.tool
+ def inner() -> str:
+ return "inner"
+
+ @mcp.tool
+ async def outer(ctx: Context) -> str:
+ result = await ctx.fastmcp.call_tool("inner", {})
+ return str(result.structured_content)
+
+ async with Client(mcp) as client:
+ await client.call_tool("outer", {})
+
+ (server,) = self._server_spans(trace_exporter)
+ assert server.name == "tools/call outer"
+
+ async def test_proxied_backend_keeps_its_own_server_span(
+ self, trace_exporter: InMemorySpanExporter
+ ):
+ backend = FastMCP("backend")
+
+ @backend.tool
+ def hello() -> str:
+ return "world"
+
+ proxy = FastMCPProxy(client_factory=lambda: ProxyClient(backend))
+
+ async with Client(proxy) as client:
+ await client.call_tool("hello", {})
+
+ names = sorted(s.name for s in self._server_spans(trace_exporter))
+ assert names == ["tools/call hello", "tools/call hello"]
+ backend_span = next(
+ s
+ for s in self._server_spans(trace_exporter)
+ if s.attributes is not None
+ and s.attributes.get("fastmcp.server.name") == "backend"
+ )
+ assert backend_span.attributes is not None
+ assert backend_span.attributes.get("fastmcp.component.key") == "tool:hello@"