Tracing

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

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.

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

Data AttributeTypeRequirement LevelDescriptionExample
mcp.method.namestringrequiredThe name of the request or notification method."tools/call"
mcp.request.idstringoptionalA unique identifier for the request."42"
mcp.session.idstringoptionalIdentifies the MCP session. Can be undefined as MCP servers can be stateless."191c4850af6c49..."
mcp.transportstringrequiredThe transport method used for MCP communication. [2]"stdio"
network.transportstringrequiredOSI transport layer protocol. [3]"pipe"
network.protocol.versionstringoptionalThe version of JSON RPC protocol used."2.0"

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

ValueDescription
"http"HTTP transport
"sse"Server-Sent Events transport
"stdio"Standard input/output transport
"unknown"*Unknown transport (for custom transports)

*"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:

ValueDescription
"pipe"Named pipe (for stdio transport)
"tcp"TCP (for HTTP/SSE transport)

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

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:

Data AttributeTypeRequirement LevelDescriptionExample
mcp.tool.result.is_errorbooleanoptionalWhether the tool execution resulted in an error.true
mcp.tool.result.content_countintoptionalNumber of content items in the tool result.3
mcp.tool.result.contentstringoptionalSerialized content of the tool result. [0]"[{\"type\":\"text\"}]"
mcp.request.argument.<key>stringoptionalArguments passed to the tool. [1]"Seattle, WA"

[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.

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:

Data AttributeTypeRequirement LevelDescriptionExample
mcp.request.argument.<key>stringoptionalAdditional arguments passed to the prompt. [1]"javascript"

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:

Data AttributeTypeRequirement LevelDescriptionExample
mcp.resource.namestringoptionalThe name of the resource being accessed."sentry-docs-platform"

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:

Data AttributeTypeRequirement LevelDescriptionExample
client.addressstringoptionalClient address - domain name or IP address."127.0.0.1"
client.portintoptionalClient port number.8080

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).
Previous
Errors
Next
Telemetry
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").