OTEL: Instrument all MCP methods, not just tools/call, resources/read, prompts/get

[strawgate]

Summary

FastMCP instruments 3 of 29 well-known MCP methods. The MCP Semantic Conventions define mcp.method.name values for all 29. This issue tracks adding CLIENT + SERVER spans for the missing methods.

Currently instrumented (3 of 29)

Method	CLIENT	SERVER
tools/call	✅	✅
resources/read	✅	✅
prompts/get	✅	✅

High-priority missing methods

Method	Notes
tools/list	Called frequently for tool discovery — currently invisible in traces
resources/list	Resource discovery
resources/templates/list	Template discovery
prompts/list	Prompt discovery
initialize	Connection lifecycle — can't see session setup in traces
sampling/createMessage	LLM sampling — where most time and cost is spent in agentic servers
ping	Health checks

Lower-priority methods

Method	Notes
completion/complete	Auto-completion
elicitation/create	User input elicitation
resources/subscribe / resources/unsubscribe	Resource subscriptions
roots/list	Root directory listing
logging/setLevel	Log level changes
notifications/* (10 methods)	Change notifications — at minimum notifications/tools/list_changed

delegate span review

The INTERNAL delegate {name} span emitted on mounted server delegation currently:

• Has only 2 vendor attributes (fastmcp.provider.type, fastmcp.component.key)
• Missing mcp.method.name (set on all other spans)
• Not in the MCP spec

The parent SERVER span already carries fastmcp.provider.type=FastMCPProvider and fastmcp.delegate.original_name. Consider either removing the delegate span or adding mcp.method.name for consistency.

Methodology

Full audit: https://github.com/strawgate/fastmcp-pr-review/blob/main/otel-audit.md

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 55s —— View job

---

Triage summary

Good audit — agree with the scope and priorities. The existing server_span / client_span helpers in src/fastmcp/server/telemetry.py and src/fastmcp/client/telemetry.py already emit the exact MCP/RPC semantic convention attributes the missing methods need; extending coverage is mostly a plumbing job (one with ..._span(...) wrapper per call site), not new design. The delegate span is a fair callout but I'd keep and fix rather than remove.

Recommendation

Implement this in two PRs to keep review tractable:

PR 1 — High-priority methods + delegate fix (the bulk of observability value):

• Add SERVER spans in FastMCP for tools/list, resources/list, resources/templates/list, prompts/list at the existing run_middleware=False branches (server.py:625, 749, 880, 1006).
• Add CLIENT spans in src/fastmcp/client/mixins/{tools,resources,prompts}.py around the list_*_mcp calls and in src/fastmcp/client/client.py around initialize (client.py:507) and ping (client.py:770).
• Add a CLIENT span around session.create_message at src/fastmcp/server/sampling/run.py:527 (this is the sampling call from server → client, so it is CLIENT kind from the MCP server's POV).
• Add mcp.method.name to delegate_span (server/telemetry.py:110); keep the span — it is useful for visualizing which mounted sub-server handled a request, which the parent SERVER span cannot show on its own.

PR 2 — Lower-priority methods + notifications once the pattern is established. Notifications should use SpanKind.PRODUCER on the sender and SpanKind.CONSUMER on the receiver (not CLIENT/SERVER), which is why they want their own helper.

This is closely related to #3886 (attribute compliance) and #3733 (metrics). Consider landing #3886 first so new spans are emitted with the already-corrected attribute set.

Findings

Current instrumentation surface (verified by grepping server_span|client_span|delegate_span):

SERVER spans emitted from src/fastmcp/server/server.py:

• server.py:1206 — tools/call
• server.py:1343 — resources/read
• server.py:1508 — prompts/get

CLIENT spans emitted from client mixins and proxy:

• src/fastmcp/client/mixins/tools.py:142 — tools/call
• src/fastmcp/client/mixins/resources.py:195 — resources/read
• src/fastmcp/client/mixins/prompts.py:128 — prompts/get
• src/fastmcp/server/providers/proxy.py:{121,237,452} — proxy delegation for the same three methods

INTERNAL spans:

• src/fastmcp/server/providers/fastmcp_provider.py:{141,234,313,432} — delegate_span on in-process mount delegation (tool/resource/template/prompt).

The server_span helper (server/telemetry.py:56-96) already emits rpc.system=mcp, rpc.service, rpc.method, mcp.method.name, fastmcp.server.name, fastmcp.component.type, fastmcp.component.key, auth attrs (enduser.id, enduser.scope), and mcp.session.id — all compliant with MCP semconv. Trace context is extracted from request_ctx.meta automatically. client_span (client/telemetry.py:11-44) is similarly complete. So the incremental cost of each new method is essentially one with server_span(...) / with client_span(...) line.

Site locations for the missing high-priority methods (already have middleware context built at these points, so the span boundary is natural):

Method	Server file:line	Client file:line
tools/list	server.py near 625 (after middleware dispatch)	client/mixins/tools.py ~L57 (list_tools_mcp)
resources/list	server.py near 749	client/mixins/resources.py ~L54
resources/templates/list	server.py near 880	client/mixins/resources.py ~L124
prompts/list	server.py near 1006	client/mixins/prompts.py ~L55
initialize	src/fastmcp/server/low_level.py:113 (inside call_original_handler)	src/fastmcp/client/client.py:507
ping	handled by MCP SDK directly — no FastMCP hook; SERVER span not straightforward	src/fastmcp/client/client.py:770 (ping)
sampling/createMessage	N/A on server (server is the caller)	src/fastmcp/server/sampling/run.py:527 — wrap context.session.create_message in CLIENT span

Why keep delegate_span: when server A mounts server B and a tool call arrives at A, the SERVER span on A cannot by itself tell you whether the call was served locally or delegated to B. The INTERNAL delegate {name} span makes the delegation edge visible in the trace tree, and if you propagate trace context into the mounted server's middleware (which this setup does via request_ctx.meta) the child server span chains under it. Removing it would merge that edge into the parent span and lose the signal. Fixing it to include mcp.method.name (e.g. tools/call, resources/read) brings it in line with the other spans for filtering/aggregation. Vendor-only INTERNAL spans are allowed by OTEL — the MCP spec doesn't need to cover them.

ping caveat: the MCP Python SDK handles ping in its low-level ServerSession without calling through FastMCP's middleware or handler layer, so there is no natural site to instrument a SERVER span for it without either monkey-patching the SDK or intercepting in MiddlewareServerSession._received_request. The CLIENT span is trivial (client.py:770); the SERVER span is worth documenting as a separate sub-task with a known workaround path (extend _received_request to dispatch PingRequest through middleware, analogous to the InitializeRequest branch at low_level.py:87-149).

Detailed Action Plan

PR 1 — High-priority methods + delegate fix

1. Extend delegate_span with mcp.method.name (src/fastmcp/server/telemetry.py)

Change signature to accept method: str and set the attribute alongside the existing ones. Update all four call sites in src/fastmcp/server/providers/fastmcp_provider.py to pass the corresponding method name (tools/call, resources/read, resources/read for templates since MCP has no distinct template-read method, prompts/get).

2. Add SERVER spans for list methods (src/fastmcp/server/server.py)

In each of list_tools, list_resources, list_resource_templates, list_prompts, wrap the post-middleware core-logic block (the branch after if run_middleware: returns) in:

with server_span(
    "tools/list",              # span name — list methods have no target, so just the method
    "tools/list",              # mcp.method.name
    self.name,
    "tool",                    # component_type — keep existing convention
    "",                        # component_key — empty for list methods (no specific target)
) as span:
    ...existing logic...
    span.set_attribute("mcp.result.count", len(authorized))  # useful custom attr

Consider whether fastmcp.component.key should be omitted for list methods rather than empty — look at #3886 for the attribute-compliance direction before finalizing.

3. Add CLIENT spans for list methods and ping (src/fastmcp/client/mixins/*.py, src/fastmcp/client/client.py)

In each list_*_mcp (tools.py:39, resources.py:39 and 108, prompts.py:39), wrap the self.session.list_*(cursor=cursor) call in client_span("tools/list", "tools/list", "", session_id=self.transport.get_session_id()). Same pattern for ping (client.py:768) and initialize (client.py:507).

4. SERVER span for initialize (src/fastmcp/server/low_level.py)

Add server_span(...) inside call_original_handler at line 113, before await super(...)._received_request(responder). Method name is "initialize"; pass self.fastmcp.name as server name. component_type / component_key don't really apply here — consider making those parameters optional on server_span (requires a small helper change).

5. CLIENT span for sampling/createMessage (src/fastmcp/server/sampling/run.py:527)

Wrap the await context.session.create_message(...) call in client_span("sampling/createMessage", "sampling/createMessage", "", session_id=...). Extract session_id from context.session_id if available. This one is particularly valuable since sampling is usually the most expensive span in an agentic server.

6. Tests

Mirror the existing tests in tests/server/telemetry/test_server_tracing.py and tests/client/telemetry/test_client_tracing.py — for each new span, assert span.name, span.kind, and the required attributes. A single parametrized test per side (server/client) covering all list methods would keep the test file compact.

7. Optional helper refactor — if server_span's component_type/component_key become awkward for list/lifecycle methods, consider making them Optional[str] and only emitting the attributes when present. Do this in the same PR to avoid churn.

PR 2 — Lower-priority methods + notifications

• completion/complete, elicitation/create, resources/subscribe/unsubscribe, roots/list, logging/setLevel: same pattern as list methods.
• Notifications: add a new notification_span helper with SpanKind.PRODUCER (sender) / SpanKind.CONSUMER (receiver), set mcp.method.name to the notification method, and instrument at minimum notifications/tools/list_changed, notifications/resources/list_changed, notifications/prompts/list_changed, notifications/roots/list_changed, notifications/cancelled, notifications/progress, and notifications/message.

Out-of-scope guardrails

• Do not rename or re-home existing span names — downstream users may already be querying them.
• Defer metric emissions to Support mcp.server.* OTEL metrics #3733.
• Defer attribute-compliance tweaks to OTEL: Fix attribute compliance with MCP semantic conventions #3886 (or land that first and rebase).

Related Items

Repository	Issue or PR	Relevance
PrefectHQ/fastmcp	#3886	Fixes attribute-name compliance with MCP semconv — should land before or with this to avoid emitting non-compliant attributes on newly instrumented methods.
PrefectHQ/fastmcp	#3733	Adds mcp.server.* OTEL metrics — complementary to spans; share some attribute/convention decisions.
PrefectHQ/fastmcp	#3888	Docs on emitting custom spans from user code — related companion for the user-facing surface.
PrefectHQ/fastmcp	#3534	GenAI semconv support — related semconv family.
PrefectHQ/fastmcp	#3535	Setting span attributes at start_as_current_span — pattern alignment.
PrefectHQ/fastmcp	#3451	Interop with MCP SDK OTEL instrumentation — watch for double-spanning when both layers emit.
PrefectHQ/fastmcp	#2813 (closed)	Original native OTEL integration — historical context.

Related Files

File	Relevance	Key lines
src/fastmcp/server/telemetry.py	Defines server_span and delegate_span helpers	56-96, 99-123
src/fastmcp/client/telemetry.py	Defines client_span helper	11-44
src/fastmcp/telemetry.py	Tracer, trace-context propagation primitives	38-111
src/fastmcp/server/server.py	Current SERVER span sites; natural home for list-method spans	1206, 1343, 1508; 602-647, 734-, 880-, 1006-
src/fastmcp/server/low_level.py	initialize middleware branch — home for initialize SERVER span	87-149
src/fastmcp/client/client.py	ping, initialize, set_logging_level, send_roots_list_changed — client-side call sites	507, 768-771, 802-808
src/fastmcp/client/mixins/tools.py	list_tools_mcp, call_tool_mcp	39-60, 142
src/fastmcp/client/mixins/resources.py	list_resources_mcp, list_resource_templates_mcp, read_resource_mcp	39-60, 108-130, 195
src/fastmcp/client/mixins/prompts.py	list_prompts_mcp, get_prompt_mcp	39-60, 128
src/fastmcp/server/sampling/run.py	Call site for session.create_message — natural sampling CLIENT span	527
src/fastmcp/server/providers/fastmcp_provider.py	delegate_span call sites — need mcp.method.name	141, 234, 313, 432
src/fastmcp/server/providers/proxy.py	Proxy CLIENT spans — pattern reference	121, 237, 452
tests/server/telemetry/test_server_tracing.py	Test patterns to mirror for new SERVER spans	entire file
tests/client/telemetry/test_client_tracing.py	Test patterns for new CLIENT spans	entire file

Related Webpages

Name	URL	Relevance
MCP Semantic Conventions	https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/	Defines mcp.method.name values and required attributes per method.
OTEL span kinds	https://opentelemetry.io/docs/specs/otel/trace/api/#spankind	Guidance on CLIENT/SERVER/PRODUCER/CONSUMER/INTERNAL — relevant for the delegate-span and notification-span design.
Issue author's full audit	https://github.com/strawgate/fastmcp-pr-review/blob/main/otel-audit.md	The methodology and full coverage table behind this issue.

---

Marvin Context Protocol | Type /marvin to interact further

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