Repository navigation
MCP semantic conventions - #2083
Conversation
brunobat
left a comment
There was a problem hiding this comment.
Thanks!
In general this seems reasonable.
Just added 2 comments.
Co-authored-by: Aaron Abbott <aaronabbott@google.com>
|
Draft of the blogpost in case it helps with the review: https://github.com/lmolkova/opentelemetry.io/blob/6fed6dfb4839b661ed269b67dc16f653f48ae9f4/content/en/blog/2026/mcp-semantic-conventions.md |
jsuereth
left a comment
There was a problem hiding this comment.
Nice! I like how you've worded the context propagation component to be forward compatible.
…en-telemetry/semantic-conventions#2083 - Change mcp.tool.name to gen_ai.tool.name - Change mcp.prompt.name to gen_ai.prompt.name - Change mcp.request.id to jsonrpc.request.id - Change rpc.jsonrpc.error_code to rpc.response.status_code - Update network.transport values from 'stdio' to 'pipe' and 'sse'/'http' to 'tcp' - Add gen_ai.operation.name attribute (value: 'execute_tool' for tools/call) - Update histogram bucket boundaries to match semantic conventions spec - Update tests to verify new attribute names Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>
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. Changes: - Span names now follow `{method} {target}` format (e.g., `tools/call greet`) - Added `mcp.method.name` and `mcp.resource.uri` attributes - Renamed `fastmcp.session.id` to standard `mcp.session.id` - Kept fastmcp.* attributes for server name, component info, provider details 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Hey! We built a TypeScript implementation of these MCP semantic conventions in toad-eye — an open-source observability toolkit for MCP servers. What we implemented based on this spec:
Also added MCP-specific metrics ( 11 Grafana dashboards auto-provisioned, including 3 MCP-specific ones. Happy to share feedback on the spec from an implementer's perspective if that's useful. |
Align Sentry MCP attributes with the OTel MCP semantic conventions that merged in open-telemetry/semantic-conventions#2083 (Jan 2026). OTel's MCP convention is deliberately minimal: only 4 mcp.* registry attributes, reusing existing gen_ai.*, network.*, jsonrpc.*, and error.* namespaces for everything else. This commit brings Sentry conventions in line with that approach. Changes: Set is_in_otel=true on 4 direct matches: - mcp.method.name - mcp.protocol.version - mcp.resource.uri - mcp.session.id Deprecated 7 attributes with backfill to OTel equivalents: - mcp.tool.name → gen_ai.tool.name - mcp.prompt.name → gen_ai.prompt.name - mcp.tool.result.content → gen_ai.tool.call.result - mcp.tool.result.is_error → error.type - mcp.request.id → jsonrpc.request.id - mcp.transport → network.transport - mcp.resource.protocol → network.protocol.name Created 3 new attributes: - gen_ai.prompt.name (OTel gen_ai registry, aliased from mcp.prompt.name) - jsonrpc.request.id (OTel MCP common refs, aliased from mcp.request.id) - jsonrpc.protocol.version (OTel MCP common refs) 27 Sentry-only attributes remain unchanged (mcp.client.*, mcp.server.*, mcp.logging.*, mcp.progress.*, mcp.prompt.result.*, etc.) — these have no OTel equivalent.
Align Sentry MCP attributes with the OTel MCP semantic conventions that merged in open-telemetry/semantic-conventions#2083 (Jan 2026). OTel's MCP convention is deliberately minimal: only 4 mcp.* registry attributes, reusing existing gen_ai.*, network.*, jsonrpc.*, and error.* namespaces for everything else. This commit brings Sentry conventions in line with that approach. Changes: Set is_in_otel=true on 4 direct matches: - mcp.method.name - mcp.protocol.version - mcp.resource.uri - mcp.session.id Deprecated 7 attributes with backfill to OTel equivalents: - mcp.tool.name → gen_ai.tool.name - mcp.prompt.name → gen_ai.prompt.name - mcp.tool.result.content → gen_ai.tool.call.result - mcp.tool.result.is_error → error.type - mcp.request.id → jsonrpc.request.id - mcp.transport → network.transport - mcp.resource.protocol → network.protocol.name Created 3 new attributes: - gen_ai.prompt.name (OTel gen_ai registry, aliased from mcp.prompt.name) - jsonrpc.request.id (OTel MCP common refs, aliased from mcp.request.id) - jsonrpc.protocol.version (OTel MCP common refs) 27 Sentry-only attributes remain unchanged (mcp.client.*, mcp.server.*, mcp.logging.*, mcp.progress.*, mcp.prompt.result.*, etc.) — these have no OTel equivalent.
* feat(mcp): align MCP attributes with OTel semantic conventions Align Sentry MCP attributes with the OTel MCP semantic conventions that merged in open-telemetry/semantic-conventions#2083 (Jan 2026). OTel's MCP convention is deliberately minimal: only 4 mcp.* registry attributes, reusing existing gen_ai.*, network.*, jsonrpc.*, and error.* namespaces for everything else. This commit brings Sentry conventions in line with that approach. Changes: Set is_in_otel=true on 4 direct matches: - mcp.method.name - mcp.protocol.version - mcp.resource.uri - mcp.session.id Deprecated 7 attributes with backfill to OTel equivalents: - mcp.tool.name → gen_ai.tool.name - mcp.prompt.name → gen_ai.prompt.name - mcp.tool.result.content → gen_ai.tool.call.result - mcp.tool.result.is_error → error.type - mcp.request.id → jsonrpc.request.id - mcp.transport → network.transport - mcp.resource.protocol → network.protocol.name Created 3 new attributes: - gen_ai.prompt.name (OTel gen_ai registry, aliased from mcp.prompt.name) - jsonrpc.request.id (OTel MCP common refs, aliased from mcp.request.id) - jsonrpc.protocol.version (OTel MCP common refs) 27 Sentry-only attributes remain unchanged (mcp.client.*, mcp.server.*, mcp.logging.*, mcp.progress.*, mcp.prompt.result.*, etc.) — these have no OTel equivalent. * fix(mcp): add reciprocal alias entries for MCP deprecations The backfill deprecations on mcp.tool.name and mcp.tool.result.content point to gen_ai.tool.name and gen_ai.tool.call.result respectively, but the target attributes were missing the reciprocal alias entries. Add mcp.tool.name and mcp.tool.result.content to the alias arrays of their replacement attributes to maintain symmetric alias-group metadata. Regenerated JS and Python attribute files to reflect the changes. * fix(mcp): Add symmetric aliases and update name templates for deprecated MCP attributes Fix CI failures caused by asymmetric alias relationships and deprecated attribute references in name templates: - Add reciprocal aliases to mcp.tool.result.content for the full alias group (gen_ai.tool.call.result, gen_ai.tool.message, gen_ai.tool.output) - Add mcp.tool.result.content to gen_ai.tool.message and gen_ai.tool.output alias lists - Add alias list to mcp.tool.name (gen_ai.tool.name, ai.function_call) - Add mcp.tool.name to ai.function_call alias list - Update mcp.json name templates to use gen_ai.tool.name and gen_ai.prompt.name instead of deprecated mcp.tool.name and mcp.prompt.name * fix(jsonrpc): Change pii to 'maybe' for jsonrpc.protocol.version and jsonrpc.request.id Address review feedback from loewenheim: string attributes should default to pii 'maybe' unless scrubbing would cause product degradation.
Fixes #2043
Adds the first version of MCP conventions including spans and basic metrics.
Implementations/prototypes:
Here's a draft of the blog: https://github.com/lmolkova/opentelemetry.io/blob/6fed6dfb4839b661ed269b67dc16f653f48ae9f4/content/en/blog/2026/mcp-semantic-conventions.md