Adopt OpenTelemetry MCP semantic conventions

[chrisguidry]

Updates FastMCP's telemetry to align with the new MCP semantic conventions from open-telemetry/semantic-conventions#2083. This gives us interoperability with other MCP implementations while keeping fastmcp.* attributes for things unique to our framework.

# Span names now follow the standard format
with server_span("tools/call greet", ...):  # was "tool greet"
    ...

Changes:

• Span names now follow {method} {target} format (e.g., tools/call greet, resources/read config://app)
• Added mcp.method.name and mcp.resource.uri standard attributes
• Renamed fastmcp.session.id to standard mcp.session.id
• Kept fastmcp.* attributes for server name, component info, and provider details

🤖 Generated with Claude Code

[coderabbitai]

Walkthrough

This pull request standardizes telemetry span naming across the MCP implementation to follow MCP semantic conventions. Span names are updated from "tool", "resource", and "prompt" to "tools/call", "resources/read", and "prompts/get" respectively in client, server, and proxy implementations. A new optional resource_uri parameter is introduced to the client_span and server_span functions in their respective telemetry modules. Span attributes are expanded to include MCP-specific semantic conventions (mcp.method.name, mcp.session.id, mcp.resource.uri) and RPC semantics, alongside existing FastMCP custom attributes. Documentation is updated to reflect the new naming conventions and expanded attributes reference.

Possibly related PRs

• Add OpenTelemetry tracing support #2869: Introduced the initial telemetry codepaths for client/server span instrumentation that this PR updates with MCP semantic conventions and resource URI tracking.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides clear context, explains the changes and their rationale, but does not follow the repository's required checklist template with issue reference and contributor/review checkboxes.	Add the required checklist sections from the template including issue reference (closes #...), development workflow confirmation, testing confirmation, documentation updates, self-review, and readiness confirmation.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: adopting OpenTelemetry MCP semantic conventions across the telemetry system.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 24467ea and eaf2906.

⛔ Files ignored due to path filters (3)

• tests/client/telemetry/test_client_tracing.py is excluded by none and included by none
• tests/server/telemetry/test_provider_tracing.py is excluded by none and included by none
• tests/server/telemetry/test_server_tracing.py is excluded by none and included by none

📒 Files selected for processing (6)

• docs/servers/telemetry.mdx
• src/fastmcp/client/client.py
• src/fastmcp/client/telemetry.py
• src/fastmcp/server/providers/proxy.py
• src/fastmcp/server/server.py
• src/fastmcp/server/telemetry.py

🧰 Additional context used

📓 Path-based instructions (2)

**/*.py

📄 CodeRabbit inference engine (AGENTS.md)

**/*.py: Python ≥3.10 with full type annotations required for all code
Never use bare except - be specific with exception types in Python code

Files:

• src/fastmcp/server/server.py
• src/fastmcp/client/telemetry.py
• src/fastmcp/client/client.py
• src/fastmcp/server/telemetry.py
• src/fastmcp/server/providers/proxy.py

docs/**/*.mdx

📄 CodeRabbit inference engine (docs/.cursor/rules/mintlify.mdc)

docs/**/*.mdx: Use clear, direct language appropriate for technical audiences
Write in second person ('you') for instructions and procedures in MDX documentation
Use active voice over passive voice in MDX technical documentation
Employ present tense for current states and future tense for outcomes in MDX documentation
Maintain consistent terminology throughout all MDX documentation
Keep sentences concise while providing necessary context in MDX documentation
Use parallel structure in lists, headings, and procedures in MDX documentation
Lead with the most important information using inverted pyramid structure in MDX documentation
Use progressive disclosure in MDX documentation: present basic concepts before advanced ones
Break complex procedures into numbered steps in MDX documentation
Include prerequisites and context before instructions in MDX documentation
Provide expected outcomes for each major step in MDX documentation
End sections with next steps or related information in MDX documentation
Use descriptive, keyword-rich headings for navigation and SEO in MDX documentation
Focus on user goals and outcomes rather than system features in MDX documentation
Anticipate common questions and address them proactively in MDX documentation
Include troubleshooting for likely failure points in MDX documentation
Provide multiple pathways (beginner vs advanced) but offer an opinionated path to avoid overwhelming users in MDX documentation
Always include complete, runnable code examples that users can copy and execute in MDX documentation
Show proper error handling and edge case management in MDX code examples
Use realistic data instead of placeholder values in MDX code examples
Include expected outputs and results for verification in MDX code examples
Test all code examples thoroughly before publishing in MDX documentation
Specify language and include filename when relevant in MDX code examples
Add explanatory comments for complex logic in MDX code examples
Document all API...

Files:

• docs/servers/telemetry.mdx

🧠 Learnings (4)

📓 Common learnings

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:55.006Z
Learning: Maintain consistency across all four MCP object types (Tools, Resources, Resource Templates, and Prompts) when implementing similar features

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:55.006Z
Learning: Applies to src/tools/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Tools (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:55.006Z
Learning: Applies to src/resources/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Resources (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

📚 Learning: 2026-01-12T16:24:55.006Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:55.006Z
Learning: Applies to src/tools/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Tools (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Applied to files:

• src/fastmcp/server/server.py
• docs/servers/telemetry.mdx

📚 Learning: 2026-01-12T16:24:55.006Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:55.006Z
Learning: Applies to src/prompts/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Prompts (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Applied to files:

• src/fastmcp/server/server.py

📚 Learning: 2026-01-12T16:24:55.006Z

Learnt from: CR
Repo: jlowin/fastmcp PR: 0
File: .cursor/rules/core-mcp-objects.mdc:0-0
Timestamp: 2026-01-12T16:24:55.006Z
Learning: Applies to src/resources/**/*.{ts,tsx,js,jsx} : Changes affecting MCP Resources (like adding tags, importing, etc.) must be adopted, applied, and tested consistently

Applied to files:

• docs/servers/telemetry.mdx
• src/fastmcp/client/client.py

🧬 Code graph analysis (3)

src/fastmcp/client/telemetry.py (1)

src/fastmcp/server/context.py (1)

• session_id (453-502)

src/fastmcp/client/client.py (3)

src/fastmcp/server/context.py (2)

• session_id (453-502)
• transport (422-428)

src/fastmcp/client/transports.py (2)

• get_session_id (124-126)
• get_session_id (310-316)

src/fastmcp/server/server.py (1)

• name (462-463)

src/fastmcp/server/telemetry.py (1)

src/fastmcp/server/context.py (1)

• session_id (453-502)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Analyze (python)
• GitHub Check: Run tests: Python 3.10 on windows-latest
• GitHub Check: Run tests: Python 3.13 on ubuntu-latest
• GitHub Check: Run tests: Python 3.10 on ubuntu-latest
• GitHub Check: Run tests with lowest-direct dependencies

🔇 Additional comments (15)

src/fastmcp/server/server.py (3)

1475-1477: LGTM! Span naming follows MCP semantic conventions.

The tools/call {name} format aligns with OpenTelemetry MCP semantic conventions. The span correctly passes method name and component details for telemetry.

---

1569-1576: LGTM! Resource span includes resource_uri for MCP compliance.

The span naming resources/read {uri} and the addition of resource_uri=uri aligns with MCP semantic conventions. This enables the mcp.resource.uri attribute to be set on resource read spans.

---

1688-1690: LGTM! Prompt span naming follows MCP conventions.

The prompts/get {name} format is consistent with the other operation span updates and aligns with MCP semantic conventions.

src/fastmcp/client/client.py (3)

883-889: LGTM! Client resource span includes resource_uri for distributed tracing.

The resources/read {uri} span naming and resource_uri=uri_str parameter align with the server-side changes and MCP semantic conventions. This enables end-to-end tracing with consistent mcp.resource.uri attributes.

---

1104-1109: LGTM! Client prompt span naming is consistent.

The prompts/get {name} format matches the server-side span naming and MCP conventions.

---

1396-1401: LGTM! Client tool span naming is consistent.

The tools/call {name} format matches the server-side span naming and MCP conventions.

src/fastmcp/client/telemetry.py (1)

11-44: LGTM! Client telemetry aligned with MCP semantic conventions.

The implementation correctly:

• Adds RPC semantic conventions (rpc.system, rpc.method)
• Implements MCP conventions (mcp.method.name, mcp.session.id, mcp.resource.uri)
• Retains FastMCP-specific attributes with fastmcp. prefix
• Conditionally adds optional attributes to avoid empty values

The attribute naming aligns with the OpenTelemetry MCP semantic conventions documentation.

src/fastmcp/server/telemetry.py (2)

30-41: LGTM! Session attribute renamed to MCP convention.

The change from fastmcp.session.id to mcp.session.id aligns with MCP semantic conventions for interoperability with other MCP implementations.

---

55-96: LGTM! Server span implementation follows MCP semantic conventions.

The restructured server_span function correctly:

• Implements RPC conventions (rpc.system, rpc.service, rpc.method)
• Implements MCP conventions (mcp.method.name, mcp.resource.uri)
• Retains FastMCP-specific attributes (fastmcp.server.name, fastmcp.component.*)
• Merges auth and session attributes cleanly
• Conditionally adds resource_uri only when provided

The implementation mirrors the client telemetry changes while adding server-specific attributes like rpc.service.

docs/servers/telemetry.mdx (3)

58-65: LGTM! Documentation updated with MCP semantic conventions.

The span naming table correctly reflects the implementation changes and includes a helpful link to the official MCP semantic conventions documentation.

---

192-241: LGTM! Comprehensive attributes reference section.

The expanded documentation clearly categorizes attributes into:

• RPC semantic conventions (standard OpenTelemetry)
• MCP semantic conventions (interoperability)
• Auth attributes (standard identity conventions)
• FastMCP custom attributes (framework-specific)

This organization helps users understand which attributes are standardized vs. framework-specific.

---

276-279: LGTM! Test example updated to match new span naming.

The assertion s.name == "tools/call hello" correctly reflects the new MCP convention span naming format.

src/fastmcp/server/providers/proxy.py (3)

117-120: LGTM! Span naming follows MCP semantic conventions.

The span name update to "tools/call {backend_name}" correctly follows the "{method} {target}" format specified in the OpenTelemetry MCP semantic conventions.

---

224-229: LGTM! Resource span naming with proper URI attribute.

The span name update correctly follows MCP semantic conventions. The addition of resource_uri=backend_uri enables the mcp.resource.uri attribute to be set per the OpenTelemetry MCP semantic conventions.

---

439-441: LGTM! Consistent span naming across MCP object types.

The span name update to "prompts/get {backend_name}" maintains consistency with the other MCP object types (tools/call, resources/read), following the "{method} {target}" format. Based on learnings, this aligns with the requirement to maintain consistency across all MCP object types.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}