getsentry / getsentry/sentry-javascript

mcp-server integration: align attribute names to current OTel GenAI/MCP semconv

Open
#21,482 2 comments 0 reactions 0 assignees View on GitHub
Improvement javascript Spans
Dominant language
TypeScript
Stars
8.7k
Forks
1.8k
Avg merge
1d 17h
Merged PRs (30d)
515

Description

The MCP server integration's `attributes.ts` is pinned to an old draft of the OTel MCP spec ([commit `3097fb0`](https://github.com/open-telemetry/semantic-conventions/blob/3097fb0af5b9492b0e3f55dc5f6c21a3dc2be8df/docs/gen-ai/mcp.md) in the now-deprecated `open-telemetry/semantic-conventions` repo). The spec has since moved to [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai) and the attribute names have materially changed.

## Wrong attribute names

The following SDK constants emit the wrong attribute key. Each has a verified spec equivalent.

| SDK constant | Emits | Should emit | Requirement level | Source |
|---|---|---|---|---|
| `MCP_TOOL_NAME_ATTRIBUTE` | `mcp.tool.name` | `gen_ai.tool.name` | Conditionally required (tool calls) | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
| `MCP_PROMPT_NAME_ATTRIBUTE` | `mcp.prompt.name` | `gen_ai.prompt.name` | Conditionally required (prompt ops) | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
| `MCP_REQUEST_ID_ATTRIBUTE` | `mcp.request.id` | `jsonrpc.request.id` | Conditionally required (requests) | [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) |
| `MCP_TRANSPORT_ATTRIBUTE` | `mcp.transport` | `network.transport` | Recommended | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
| `MCP_REQUEST_ARGUMENT` (prefix) | `mcp.request.argument.` | `gen_ai.tool.call.arguments` (single attr) | Opt-in | [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) |
| `MCP_TOOL_RESULT_CONTENT_ATTRIBUTE` | `mcp.tool.result.content` | `gen_ai.tool.call.result` (single attr) | Opt-in | [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) |
| `MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE` | `mcp.tool.result.is_error` | `error.type = "tool_error"` | Conditionally required | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |

Notes:
- `network.transport` values SHOULD be `tcp` or `quic` for HTTP transport and `pipe` for stdio — not the MCP-level transport name.
- `gen_ai.tool.call.arguments` and `gen_ai.tool.call.result` are single serialized attributes, not per-key prefixes.
- `mcp.tool.result.content_count` has no spec equivalent at all.

## Missing attributes

| Attribute | Requirement level | Source | Notes |
|---|---|---|---|
| `gen_ai.operation.name` | Recommended | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) | SHOULD be `execute_tool` on tool call spans; allows consumers to treat MCP tool spans like other GenAI tool spans |
| `rpc.response.status_code` | Conditionally required | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) | When response contains a JSON-RPC error code |
| `jsonrpc.protocol.version` | Recommended | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) | When not `2.0` |

## Custom attributes with no spec equivalent

These are Sentry-invented attributes that don't appear in the OTel spec. They may be worth keeping as explicit Sentry extensions, but should be documented as such and should not use namespaces that conflict with or extend spec-owned ones:

- `mcp.client.name`, `mcp.client.title`, `mcp.client.version`
- `mcp.server.name`, `mcp.server.title`, `mcp.server.version`
- `mcp.logging.level`, `mcp.logging.logger`, `mcp.logging.data_type`, `mcp.logging.message`
- `mcp.prompt.result.description`, `mcp.prompt.result.message_count`, `mcp.prompt.result.message_role`, `mcp.prompt.result.message_content`

The `mcp.*` namespace in the spec covers only: `mcp.method.name`, `mcp.session.id`, `mcp.resource.uri`, `mcp.protocol.version`. Anything else under `mcp.*` risks colliding with future spec attributes.

## Spec references

- [open-telemetry/semantic-conventions-genai — model/mcp/](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/model/mcp) (current authoritative source)
- [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) — shared attributes including `gen_ai.tool.name`, `gen_ai.prompt.name`, `gen_ai.operation.name`
- [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) — span definitions with `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`
- [registry.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/registry.yaml) — full `mcp.*` attribute registry (only 4 attributes)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.