MCP Tracing

The MCP Server module is the instrumentation for the anthropic MCP SDKs. At the moment it only supports the MCP Typescript SDK.

Spans Conventions

For your MCP Server data to show up in Sentry, specific spans must be created with well-defined names and data attributes. See below.

We follow the draft OpenTelemetry MCP Semantic Conventions as closely as possible, with some opinionated additions for improved MCP observability. We should keep an eye on the conventions and update this guide as needed as they are currently in draft and subject to change.

Common Span Attributes

All MCP Server spans share common attributes and follow consistent patterns:

[2] Well-defined values for data attribute mcp.transport:

*"unknown" is a placeholder for custom transports. We could try to infer the name from the transport object.

[3] Well-defined values for data attribute network.transport:

Session Management

MCP servers can be either stateless or stateful. Understanding this distinction is important for proper tracing implementation and session data handling. (See MCP Server Session Management for more details.)

Stateless vs Stateful Servers

Stateless Servers: These servers treat each request independently without maintaining session state between requests. The mcp.session.id attribute may be undefined or not meaningful for such servers.

Stateful Servers: These servers maintain session state across multiple requests from the same client. They use a consistent mcp.session.id that is shared across all messages within the same session lifecycle. All MCP request from the client should always have the HTTP header X-MCP-Session-Id set to the same value.

Session Data Attributes

For stateful servers, additional session metadata is collected during the initialization phase and attached to all subsequent spans within the same session. This provides observability and context for the entire session lifecycle.

Session Lifecycle

1. Initialization: During the initialize request, session metadata (client info, server info, protocol version) is established and stored.

2. Session Propagation: For all subsequent requests within the same session (tool calls, prompt requests, resource access), the session metadata is automatically attached to each span.

3. Evolution: As the MCP specification evolves, additional session-level metadata may be captured and propagated, providing richer context for observability.

This session-based approach allows us to:

• Track client and server versions across infrastructure
• Analyze protocol version adoption and compatibility
• Group and correlate all operations within a single client session
• Monitor session duration and patterns

MCP Server Span Types

MCP Server spans use the operation value "mcp.server" and fall into these categories:

Server Methods (op: "mcp.server"):

• Tool calls - tools/call {tool_name} - Execute client-requested tools
• Prompt requests - prompts/get {prompt_name} - Provide prompt templates to clients
• Resource access - resources/read {resource_uri} - Serve resources to clients

Notifications (op: "mcp.notification.client_to_server" or "mcp.notification.server_to_client"):

• One-way messages that don't expect responses (e.g., notifications/cancelled)

Others (op: "mcp.server"):

• Initialization - initialize - Handle client connection setup

Tool Call Span

Describes MCP tool execution requests from clients.

• The spans op MUST be "mcp.server".
• The span name SHOULD follow the pattern "tools/call {mcp.tool.name}". (e.g. "tools/call get_weather")
• The mcp.method.name attribute MUST be "tools/call".
• The mcp.tool.name attribute SHOULD be set to the tool name. (e.g. "get_weather")
• All Common Span Attributes SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

[0]: Span attributes only allow primitive data types. This means you need to use a stringified version of a list of dictionaries. Do NOT set [{"type": "text"}] but rather the string "[{\"type\": \"text\"}]". [1]: Arguments are prefixed with mcp.request.argument. followed by the argument key. For example, if a tool receives {location: "Seattle, WA"}, it becomes mcp.request.argument.location.

Prompt Span

Describes MCP prompt requests from clients.

• The spans op MUST be "mcp.server".
• The span name SHOULD follow the pattern "prompts/get {mcp.prompt.name}". (e.g. "prompts/get analyze-code")
• The mcp.method.name attribute MUST be "prompts/get".
• The mcp.prompt.name attribute SHOULD be set to the prompt name. (e.g. "analyze-code")
• All Common Span Attributes SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

Resource Span

Describes MCP resource access requests from clients.

• The spans op MUST be "mcp.server".
• The span name SHOULD follow the pattern "resources/read {mcp.resource.uri}". (e.g. "resources/read file:///path/to/file")
• The mcp.method.name attribute MUST be "resources/read".
• The mcp.resource.uri attribute SHOULD be set to the resource URI. (e.g. "file:///path/to/file")
• All Common Span Attributes SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

Initialize Span

Describes MCP initialization requests from clients.

• The spans op MUST be "mcp.server".
• The span name SHOULD be "initialize".
• The mcp.method.name attribute MUST be "initialize".
• All Common Span Attributes SHOULD be set (all required common attributes MUST be set).

Additional attributes on the span:

Notification Span

Describes MCP notification messages (one-way messages that don't expect a response).

• The spans op MUST be "mcp.notification.client_to_server" or "mcp.notification.server_to_client".
• The span name SHOULD be the notification method name. (e.g. "notifications/cancelled")
• The mcp.method.name attribute MUST be set to the notification method. (e.g. "notifications/cancelled")
• All Common Span Attributes SHOULD be set (all required common attributes MUST be set).