dev-docs (MCP server): Add tracing and errors documentation

develop-docs/sdk/expected-features/mcp-instrumentation/errors.mdx

@@ -0,0 +1,76 @@
+---
+title: Errors
+---
+
+MCP Server error instrumentation ensures that all errors occurring within the Model Context Protocol (MCP) server are captured and reported to Sentry, **without ever interfering with the operation of the MCP service itself**. 
+
+## Goals and Philosophy
+
+- **Comprehensive context:** Errors are always associated with the active Sentry span, so you get full context (method, tool, arguments, etc.) in Sentry.
+- **Categorized errors:** Errors are tagged by type (e.g., `validation`, `timeout`, `tool_execution`, `resource_operation`, `prompt_execution`, `transport`, etc.) for easy filtering and analysis in Sentry.
+- **Handler wrapping:** All MCP server handlers (`tool`, `resource`, `prompt`) are wrapped to ensure errors are captured and correlated with the correct request span.
+
+
+## Safe Error Capture
+
+The core utility is an error capture function:
+
+```ts
+import { getClient } from '../../currentScopes';
+import { captureException } from '../../exports';
+
+export function captureError(error: Error, errorType?: string): void {
+  try {
+    const client = getClient();
+    if (!client) return;
+    captureException(error, {
+      tags: {
+        mcp_error_type: errorType || 'handler_execution',
+      },
+    });
+  } catch {
+    // Silently ignore capture errors so it never affects MCP operation
+  }
+}
+```
+
+- **Never throws an exception:** All error capture is wrapped in a try/catch and will never throw an exception.
+- **Tags errors:** [WIP] will be removed as tags are intended for users.
+
+## Handler Wrapping for Error Capture
+
+All MCP server method handlers (`tool`, `resource`, `prompt`) are wrapped to:
+- Correlate handler execution with the correct Sentry span (using request/session data)
+- Capture both synchronous and asynchronous errors
+- Categorize errors by handler type and error nature
+
+### Error Categorization
+
+Errors are categorized and tagged based on the handler and error type:
+
+- **Tool handler errors:**
+  - `validation` (e.g., protocol/validation errors)
+  - `timeout` (e.g., server timeouts)
+  - `tool_execution` (all other tool errors)
+- **Resource handler errors:**
+  - `resource_operation`
+- **Prompt handler errors:**
+  - `prompt_execution`
+- **Transport errors:**
+  - `transport`
+- **Protocol errors:**
+  - `protocol`
+
+## Span Correlation
+
+All errors are captured within the context of the active Sentry span, so you can:
+- See which MCP method, tool, or resource caused the error
+- View all arguments and context for the failed request
+- Correlate errors with traces and performance data
+
+## Transport Layer Error Instrumentation
+
+The MCP transport layer is also instrumented to:
+- Create spans for incoming/outgoing messages
+- Capture errors in transport event handlers (e.g., `onerror`)
+- Correlate protocol errors with the correct request/response

develop-docs/sdk/expected-features/mcp-instrumentation/index.mdx

@@ -0,0 +1,27 @@
+---
+title: MCP Instrumentation
+---
+
+The MCP Server module instruments Anthropic's Model Context Protocol (MCP) SDKs. At the moment it only supports the [MCP Typescript SDK](https://github.com/modelcontextprotocol/typescript-sdk/).
+
+## Features
+
+- [Tracing](./tracing)
+- [Errors](./errors)
+
+## Current limitations
+
+Currently, it doesn't support automatic instrumentation due to [this issue](https://github.com/getsentry/sentry-javascript/issues/16052) related to `import-in-the-middle`.
+
+Instrumentation must be done by wrapping the MCP server instance. This is done by the `wrapMcpServerWithSentry` function. For example:
+
+```ts
+import * as Sentry from "@sentry/core";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const mcpServer = new McpServer({
+  name: 'My MCP Server',
+});
+
+const server = Sentry.wrapMcpServerWithSentry(mcpServer);
+```

develop-docs/sdk/expected-features/mcp-instrumentation/tracing.mdx

@@ -0,0 +1,137 @@
+---
+title: Tracing
+---
+
+The MCP Server module is the instrumentation for the anthropic MCP SDKs. At the moment it only supports the [MCP Typescript SDK](https://github.com/modelcontextprotocol/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](https://github.com/open-telemetry/semantic-conventions/pull/2083) 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:
+
+| Data Attribute              | Type   | Requirement Level | Description                                                                   | Example                                |
+| :-------------------------- | :----- | :---------------- | :---------------------------------------------------------------------------- | :------------------------------------- |
+| `mcp.method.name`           | string | required          | The name of the request or notification method.                               | `"tools/call"`                         |
+| `mcp.transport`             | string | required          | The transport method used for MCP communication. **[2]**                      | `"stdio"`                              |
+| `network.transport`         | string | required          | OSI transport layer protocol. **[3]**                                         | `"pipe"`                               |
+| `mcp.request.id`            | string | optional          | A unique identifier for the request.                                          | `"42"`                                 |
+| `mcp.session.id`            | string | optional          | Identifies the MCP session. Can be undefined as MCP servers can be stateless. | `"191c4850af6c49..."`   |
+| `network.protocol.version`  | string | optional          | The version of JSON RPC protocol used.                                        | `"2.0"`                                |
+
+**[2]** Well-defined values for data attribute `mcp.transport`:
+
+| Value        | Description                              |
+| :-------     | :------------------------------------    |
+| `"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`:
+
+| Value    | Description                           |
+| :------- | :------------------------------------ |
+| `"pipe"` | Named pipe (for stdio transport)      |
+| `"tcp"`  | TCP (for HTTP/SSE transport)          |
+
+### 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](#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).
+
+Additional attributes on the span:
+
+| Data Attribute                        | Type    | Requirement Level | Description                                                                   | Example                                |
+| :------------------------------------ | :------ | :---------------- | :---------------------------------------------------------------------------- | :------------------------------------- |
+| `mcp.tool.result.is_error`            | boolean | optional          | Whether the tool execution resulted in an error.                              | `true`                                 |
+| `mcp.tool.result.content_count`       | int     | optional          | Number of content items in the tool result.                                   | `3`                                    |
+| `mcp.tool.result.content`             | string  | optional          | Serialized content of the tool result. **[0]**                                | `"[{\"type\":\"text\"}]"`              |
+| `mcp.request.argument.<key>`          | string  | optional          | Arguments 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`.
+
+### 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](#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).
+
+Additional attributes on the span:
+
+| Data Attribute                        | Type   | Requirement Level | Description                                                                   | Example                                |
+| :------------------------------------ | :----- | :---------------- | :---------------------------------------------------------------------------- | :------------------------------------- |
+| `mcp.request.argument.<key>`          | string | optional          | Additional arguments passed to the prompt. **[1]**                           | `"javascript"`                         |
+
+### 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](#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).
+
+Additional attributes on the span:
+
+| Data Attribute                        | Type   | Requirement Level | Description                                                                   | Example                                |
+| :------------------------------------ | :----- | :---------------- | :---------------------------------------------------------------------------- | :------------------------------------- |
+| `mcp.resource.name`                   | string | optional          | The name of the resource being accessed.                                      | `"sentry-docs-platform"`               |
+
+### 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](#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).
+
+Additional attributes on the span:
+
+| Data Attribute                        | Type   | Requirement Level | Description                                                                   | Example                                |
+| :------------------------------------ | :----- | :---------------- | :---------------------------------------------------------------------------- | :------------------------------------- |
+| `client.address`                      | string | optional          | Client address - domain name or IP address.                                   | `"127.0.0.1"`                          |
+| `client.port`                         | int    | optional          | Client port number.                                                           | `8080`                                 |
+
+### 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](#common-span-attributes) SHOULD be set (all `required` common attributes MUST be set).
+