OTEL: Fix attribute compliance with MCP semantic conventions

[strawgate]

Summary

FastMCP's OTEL instrumentation has attribute gaps and non-standard attributes compared to the MCP Semantic Conventions. This issue tracks bringing the existing spans into spec compliance — no new spans, just fixing what we emit.

Missing required/conditionally-required attributes

• gen_ai.tool.name — Conditionally required on tool operations. Currently not set. Should use tool.name (the public name), not fastmcp.component.key (internal registry key).
• gen_ai.prompt.name — Conditionally required on prompt operations. Same fix.
• error.type — Conditionally required on failure. Spec defines: JSON-RPC error code as string, or tool_error when CallToolResult.isError=true. Currently not set anywhere.
• jsonrpc.request.id — Conditionally required when client executes a request. Not set.
• rpc.response.status_code — Conditionally required on error responses. The only rpc.* attribute the MCP semconv references. Not set.

Missing recommended attributes

• mcp.protocol.version — Recommended on both CLIENT and SERVER
• jsonrpc.protocol.version — Recommended. Should be "2.0"
• network.transport — Recommended. Should reflect transport type (pipe, tcp, inproc)
• server.address/server.port — Recommended on CLIENT spans
• mcp.session.id on CLIENT spans — Currently only set on SERVER

Non-standard attributes to remove

The MCP semconv is standalone under gen-ai/ and explicitly recommends against RPC conventions:

"When instrumenting MCP calls, it's RECOMMENDED to follow MCP conventions instead of RPC semantic conventions"

Additionally, rpc.system was renamed to rpc.system.name and deprecated.

• Remove rpc.system = "mcp" — deprecated name, not in MCP semconv
• Remove rpc.service — not in any spec, duplicates fastmcp.server.name
• Remove rpc.method — redundant with mcp.method.name

Error handling bugs

• CLIENT span not marked ERROR on tool failure — ToolError is raised in _parse_call_tool_result() (tools.py:393) after client_span exits (tools.py:162). Span never sees the error.
• Exception recorded twice on SERVER span — server_span catches + records, then inner call_tool wraps in ToolError and re-raises, triggering a second recording.
• No status description — Spec says "status description SHOULD match JSONRPCError.message". Currently never set.

Methodology

Tested with console OTEL exporter (no vendor SDK) to capture raw spans. Full audit: https://github.com/strawgate/fastmcp-pr-review/blob/main/otel-audit.md

[marvin-context-protocol]

Claude finished @strawgate's task in 4m 0s —— View job

---

tl;dr

All findings in the audit check out against the current code. The cleanest path is to rewrite server_span / client_span in one PR: introduce typed OTEL attribute constants, drop the rpc.* attrs, add the missing gen_ai.* / mcp.* / jsonrpc.* attrs, and fix the two error-recording bugs by relocating the CLIENT span on call_tool to cover _parse_call_tool_result and dropping the duplicate record_exception path on SERVER.

This is a small, self-contained refactor (~2 files + tests). The removal of rpc.system/rpc.service/rpc.method is a breaking change for anyone filtering on those — worth calling out in release notes.

---

Findings

Verified against main (0a921f5):

Claim	File	Status
rpc.system=mcp, rpc.service, rpc.method set on SERVER	src/fastmcp/server/telemetry.py:74-78	Confirmed
rpc.system=mcp, rpc.method set on CLIENT	src/fastmcp/client/telemetry.py:27-28	Confirmed
gen_ai.tool.name / gen_ai.prompt.name never set	everywhere	Confirmed — span uses fastmcp.component.key only (components.py:262)
No error.type, jsonrpc.*, rpc.response.status_code, mcp.protocol.version, network.transport, server.address/port	all telemetry files	Confirmed
mcp.session.id on CLIENT	client/telemetry.py:34-35 accepts session_id	Partially set — call-site at proxy.py:121,237,452 passes no session_id; only the top-level Client mixins do. So it's wired for top-level client usage, but missing on proxy forwards and on most callers.
CLIENT span not marked ERROR on ToolError	client/mixins/tools.py:142-162 vs :287-289	Confirmed — _parse_call_tool_result raises after client_span exits. call_tool_mcp is the wrong scope for the span when raise_on_error=True.
Double exception record on SERVER	server/telemetry.py:93-96 + server.py:1247-1263	Confirmed pattern: tool._run failures are caught inside the with server_span block and rewrapped as ToolError before reaching the span's own except. For mounted servers, delegate_span (server/telemetry.py:120-123) ALSO records before re-raising, yielding a second exception event on the parent SERVER span.
No status description	both telemetry files	Confirmed — only Status(StatusCode.ERROR) set, no message

Related repo context:

• OTEL work was added in Add OpenTelemetry tracing support #2869, then propagation standardized in Use standard traceparent/tracestate keys per OTel MCP semconv #3221.
• Sibling issues OTEL: Instrument all MCP methods, not just tools/call, resources/read, prompts/get #3887 (missing methods) and Interoperating with OpenTelemetry instrumentation in the MCP SDK #3451 (MCP SDK interop) inform scope — this issue should not try to solve those too.

---

Detailed Action Plan

1. Centralize attribute keys in src/fastmcp/telemetry.py:

• Add constants for every OTEL key we emit (GEN_AI_TOOL_NAME = "gen_ai.tool.name", MCP_PROTOCOL_VERSION = "mcp.protocol.version", ERROR_TYPE = "error.type", etc.). Prevents typos and gives us one place to audit compliance.

2. Rewrite src/fastmcp/server/telemetry.py::server_span:

• Remove rpc.system, rpc.service, rpc.method.
• Keep mcp.method.name, fastmcp.server.name, fastmcp.component.type, fastmcp.component.key.
• Add mcp.protocol.version (from ctx.request_context.session negotiated version — expose a helper on Context or fetch from mcp.shared.session), jsonrpc.protocol.version="2.0", network.transport (pipe/tcp/inproc — derivable from request_context's transport).
• Emit gen_ai.tool.name / gen_ai.prompt.name when component_type in ("tool","prompt") using the public name (add a component_name: str | None param). Update call sites in server.py:1206, 1343, 1508 to pass the resolved tool.name / prompt.name after lookup, via span.set_attributes(...) right after the existing get_span_attributes() call.
• Leave record_exception behavior but set a span.is_recording()-guarded flag on the span (span.set_attribute("fastmcp._error_recorded", True) or use contextvars) so inner delegate_span / nested server_span skip duplicate recording.

3. Fix double-record more cleanly: instead of a flag, change the middle layer — delegate_span should NOT record exceptions (it's INTERNAL, a parent will record). Simpler. Document as: "only the outermost CLIENT/SERVER span records; INTERNAL spans re-raise without recording." Drop delegate_span's except entirely.

4. Rewrite src/fastmcp/client/telemetry.py::client_span:

• Remove rpc.system, rpc.method.
• Add jsonrpc.protocol.version="2.0", network.transport, server.address, server.port, mcp.protocol.version (all from the client's transport object — add get_otel_attributes() or similar to each transport in src/fastmcp/client/transports/).
• Add jsonrpc.request.id — harder; the MCP SDK assigns IDs inside BaseSession._send_request. Two options: (a) wrap session.send_request in a shim that captures the ID; (b) punt for now and document as best-effort. Recommend (b) for this PR, tracked as follow-up — it's conditionally required but capturing it without forking the SDK is ugly.
• Always set mcp.session.id from self.transport.get_session_id() — update proxy.py call sites at :121, :237, :452 to pass it.

5. Fix CLIENT error span scope in src/fastmcp/client/mixins/tools.py:

• Move client_span from inside call_tool_mcp (line 142) up into call_tool (line 280) so it wraps _parse_call_tool_result. Or add a second wrap in call_tool that sets error.type=tool_error + StatusCode.ERROR when result.is_error before returning.
• Cleanest: inside call_tool_mcp's with client_span(...) as span:, after the session call returns, inspect result.isError and set error.type="tool_error" + Status(ERROR, description=<first text content>) on the span. This covers the unraised path too (raise_on_error=False).
• For genuine exceptions: set error.type to the exception class name (per OTEL convention) in the except clause of client_span.

6. Map error.type per the spec:

• On McpError with JSON-RPC error code: error.type = str(code).
• On CallToolResult.isError=True: error.type = "tool_error" + Status(ERROR, description=first_text_content).
• Other exceptions: error.type = type(e).__qualname__.
• Implement as a helper record_span_error(span, exception_or_result) in fastmcp/telemetry.py (extend the existing record_span_error).

7. Tests. Expand tests/server/telemetry/test_server_tracing.py and tests/client/telemetry/test_client_tracing.py:

• Assert presence of every new required/conditionally-required attribute.
• Assert rpc.* attrs are absent.
• Assert CLIENT span is ERROR when tool returns isError=True (both raise_on_error=True and False).
• Assert exactly one exception event on SERVER span for mounted server failures (not two).
• Assert error.type="tool_error" and status description matches the tool error message.

8. Docs. Update docs/servers/telemetry.mdx with the new attribute list. Add a short note that the emitted attributes follow MCP semconv (link to spec). Call out the removal of rpc.* as a behavior change.

9. Suggested PR scope. Do NOT combine with #3887 (new spans) or #3451 (SDK interop). Keep this PR "fix attributes on existing spans" only — it's a compliance fix and release-notable as such.

Related Items

Repository	Issue or PR	Relevance
PrefectHQ/fastmcp	#2869	Original OTEL integration — defines the current attribute surface being fixed
PrefectHQ/fastmcp	#3221	Added traceparent/tracestate propagation — precedent for MCP-semconv alignment
PrefectHQ/fastmcp	#3887	Companion: adds instrumentation to missing methods; out of scope here
PrefectHQ/fastmcp	#3451	MCP SDK upstream is adding its own instrumentation — keep interop in mind for jsonrpc.request.id capture
modelcontextprotocol/python-sdk	PR #2132	Upstream SDK instrumentation — may give access to request IDs without a shim

Related Files

File	Relevance	Lines
src/fastmcp/server/telemetry.py	SERVER span — main edit target, remove rpc.*, add new attrs, fix double-record	74-96, 110-123
src/fastmcp/client/telemetry.py	CLIENT span — main edit target	24-44
src/fastmcp/telemetry.py	Extend record_span_error, add attribute-key constants	76-79
src/fastmcp/client/mixins/tools.py	Relocate/extend CLIENT span to cover isError branch	142-162, 287-289, 388-393
src/fastmcp/client/mixins/resources.py	Same client_span call site	195-201
src/fastmcp/client/mixins/prompts.py	Same	128-133
src/fastmcp/server/providers/proxy.py	Pass session_id into client_span; currently missing	121-123, 237, 452
src/fastmcp/server/server.py	Pass public name into server_span to populate gen_ai.tool.name/gen_ai.prompt.name	1206-1208, 1343-1349, 1508-1510
src/fastmcp/utilities/components.py	get_span_attributes base — possibly extend so each component emits its own gen_ai.* attr	257-262
tests/server/telemetry/test_server_tracing.py	Tests to extend	—
tests/client/telemetry/test_client_tracing.py	Tests to extend	—
docs/servers/telemetry.mdx	Update attribute table	—

Related Webpages

Name	URL	Relevance
MCP Semantic Conventions	https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/	Source of truth for attribute names and requirement levels
Deprecation of rpc.system → rpc.system.name	open-telemetry/semantic-conventions#3176	Justifies removing the current rpc.system="mcp" attribute

Checklist

• Locate OTEL instrumentation code
• Verify each reported issue against the source
• Review related issues/PRs
• Formulate recommendation and action plan

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
| Branch: claude/issue-3886-20260413-0511