# Monitor Your MCP Server with Sentry: Tools & Errors

> Add monitoring to your Node.js or Python MCP server in minutes. Track clients, transports, tool performance, error rates, and trace each request.

**URL:** https://sentry.io/cookbook/monitor-mcp-server/

---

Initialize Sentry and your MCP server is instrumented automatically. Get full visibility into client activity, transport distribution, tool and resource performance, and errors, including the silent ones MCP hides from you.

**Time:** 10-15 minutes | **Difficulty:** Beginner

## What You'll Learn

- Instrumented an MCP server with minimal setup

- Identified which clients and transports are connecting to your server

- Found your slowest and most error-prone tools and resources

- Traced individual tool calls with full input and output data

- Caught errors that MCP silently swallows

**Topics:** AI Observability, Tracing, Error Monitoring, Issues

**SDKs:** Node.js, Python

## Before you start

**SDKs & packages**

- [@sentry/node](https://docs.sentry.io/platforms/javascript/guides/node/) v9.46.0+ for JavaScript (v10.33.0+ for `recordInputs`/`recordOutputs`, v11.1.0+ for automatic instrumentation), or [sentry-sdk](https://docs.sentry.io/platforms/python/) v2.43.0+ for Python

- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) 1.x or [@modelcontextprotocol/server](https://www.npmjs.com/package/@modelcontextprotocol/server) 2.x (JavaScript) or [mcp](https://pypi.org/project/mcp/) (Python)

**Accounts & access**

- [Sentry account](https://sentry.io/signup/) with a project for your MCP server

- Access to deploy your MCP server code

**Knowledge**

- Basic understanding of [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) concepts: tools, resources, and prompts

- Familiarity with your server framework (Express, Hono, FastAPI, etc.)

## Steps

### 1. Initialize Sentry and instrument your MCP server

Import the Sentry SDK and initialize it with tracing enabled *before* anything else. Starting with SDK v11.1.0, Sentry instruments every `McpServer` instance automatically, so tool calls, resource reads, and prompt retrievals are captured with no extra code. On older SDK versions, or on Cloudflare Workers without the Sentry Cloudflare Vite plugin, wrap your `McpServer` instance with `Sentry.wrapMcpServerWithSentry()`. You can also use the wrapper on v11.1.0+ to set per-server options. It returns the same server instance and won't instrument a server twice. The `recordInputs` and `recordOutputs` options (SDK v10.33.0+) control whether tool call arguments and results are captured for this server. In SDK v11 and newer, both are recorded by default, and the global `dataCollection.genAI` option sets the default for all MCP and AI instrumentation.

```javascript
import * as Sentry from "@sentry/node";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

// Sentry init must be above everything else
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  tracesSampleRate: 1.0,
});

// On SDK v11.1.0+, every McpServer is instrumented automatically
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Optional: wrap the server to set per-server options.
// Required on SDK versions earlier than 11.1.0, and on Cloudflare
// Workers without the Sentry Cloudflare Vite plugin.
// const server = Sentry.wrapMcpServerWithSentry(
//   new McpServer({ name: "my-mcp-server", version: "1.0.0" }),
//   { recordInputs: false, recordOutputs: false }
// );

// Define your tools, resources, and prompts as usual
// server.tool(...), server.resource(...), etc.
```

[MCP monitoring setup docs](https://docs.sentry.io/product/mcp-servers/getting-started/)

### 2. (Python alternative) Add the MCP integration

If your MCP server is written in Python, add the `MCPIntegration` to your `sentry_sdk.init()` call. This works with both the high-level FastMCP API and the low-level `mcp.server.lowlevel.Server` API. Set `send_default_pii=True` to capture tool inputs and outputs.

```python
import sentry_sdk
from sentry_sdk.integrations.mcp import MCPIntegration
from mcp.server.fastmcp import FastMCP

sentry_sdk.init(
    dsn="https://examplePublicKey@o0.ingest.sentry.io/0",
    traces_sample_rate=1.0,
    send_default_pii=True,
    integrations=[MCPIntegration()],
)

mcp = FastMCP("my-mcp-server")

@mcp.tool()
async def calculate_sum(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

mcp.run()
```

[Python MCP integration docs](https://docs.sentry.io/platforms/python/integrations/mcp/)

### 3. Deploy and verify data is flowing

Deploy your MCP server and trigger a few tool calls or resource reads from any MCP client (Cursor, Claude Desktop, a custom client, etc.). Then go to your [MCP Dashboards](https://sentry.io/orgredirect/organizations/:orgslug/dashboards/?filter=onlyPrebuilt&query=mcp) in Sentry. You should see incoming requests within a few seconds.

[MCP dashboard docs](https://docs.sentry.io/product/mcp-servers/dashboard/)

### 4. Check client and transport distribution

At the top of the MCP Dashboard, two widgets show you who is connecting and how. **Traffic by Client** breaks down requests by MCP client (for example, `cursor-vscode`, `claude-desktop`, or a custom client). **Transport Distribution** shows which transport protocols are in use: Streamable HTTP, SSE (Server-Sent Events), or custom transports. Use this to understand your user base and decide which clients to optimize for, or whether to build deep-link integrations for popular clients.

[Dashboard widgets reference](https://docs.sentry.io/product/mcp-servers/dashboard/)

### 5. Identify slow and failing tools

Open the [MCP Dashboards](https://sentry.io/orgredirect/organizations/:orgslug/dashboards/?filter=onlyPrebuilt&query=mcp) and look at the tool widgets. You'll find **Most Used Tools**, **Slowest Tools**, and **Most Failing Tools**, plus a **Tools** table below them with per-tool metrics: request count, error rate, average duration, and P95 latency. If a tool is heavily used but slow, this is your signal to optimize it. If a tool has a high error rate, click into it to investigate.

[Tools performance metrics](https://docs.sentry.io/product/mcp-servers/dashboard/)

### 6. Inspect resource and prompt performance

The dashboard has equivalent tables for resources and prompts. The **Resources** table shows access patterns by URI, including request count, error rate, and latency. This is especially useful if your resources fetch data from external services, because you can identify bottlenecks quickly. **Prompts** tracks prompt template usage and performance. Each entry shows response times and error rates.

[Resource and prompt metrics](https://docs.sentry.io/product/mcp-servers/dashboard/)

### 7. Trace a specific tool call

Click into any tool from the dashboard to see its individual traces. Each trace shows the full lifecycle of a JSON-RPC request, including the tool name, execution duration, input arguments, and output results. You also get metadata like the MCP client name, transport type, request ID, and session ID. If your server is stateful, use session IDs to group all requests from the same session.

[Trace explorer docs](https://docs.sentry.io/product/trace-explorer/)

### 8. Catch errors that MCP silently swallows

The Anthropic MCP SDK handles errors by returning a JSON-RPC response instead of throwing. This means a failing tool or resource will not produce an error in your application. It just silently responds with a generic message. Sentry captures these errors anyway and links them to the specific tool, resource, or prompt that caused them. Check [Issues](https://sentry.io/orgredirect/organizations/:orgslug/issues/) to see errors broken out by tool and resource, with full stack traces and context.

[Issues overview](https://docs.sentry.io/product/issues/)

## Summary

**Your MCP server is being monitored.**

Errors and slow tool calls will show up in Sentry before your users have to report them.

## Pro Tips

- Keep `recordInputs` and `recordOutputs` (or `send_default_pii` in Python) on during development to see full tool arguments and results in traces. If your tools handle sensitive data, set them to `false` in production, or turn off recording globally with `dataCollection: { genAI: { inputs: false, outputs: false } }`.

- Use the session ID attribute to group and filter all requests from a single MCP session. This is helpful for debugging stateful server issues.

- Sentry's MCP monitoring is OpenTelemetry-compatible. If you're using a different MCP server library that follows OpenTelemetry semantic conventions for MCP, you'll get the same dashboard data.

- Check the Transport Distribution widget regularly. If you see unexpected custom transports or unknown clients, it could indicate unauthorized access.

## Common Pitfalls

- Tool call arguments and results are treated as sensitive data. In JavaScript SDK v10, you won't see them in your traces unless you set `recordInputs`/`recordOutputs` to `true` or enable them with `dataCollection.genAI`. In v11, they are recorded by default. In Python, you need `send_default_pii=True`.

- Make sure `Sentry.init()` runs before you create the MCP server. If Sentry initializes after the server, instrumentation won't attach correctly.

- The Node.js SDK requires version 9.46.0 or newer for MCP monitoring, 10.33.0 or newer for `recordInputs`/`recordOutputs`, and 11.1.0 or newer for automatic instrumentation. Support for `@modelcontextprotocol/server` 2.x requires 10.70.0 or newer. The Python SDK requires version 2.43.0 or newer. Check your installed version if data isn't appearing.

- Don't forget to set `tracesSampleRate` (or `traces_sample_rate`) to a value greater than 0. Without tracing enabled, MCP spans won't be captured.

## FAQ

**Which MCP server libraries are supported?**

For JavaScript, Sentry instruments the `McpServer` class from `@modelcontextprotocol/sdk` 1.x and `@modelcontextprotocol/server` 2.x. For Python, the integration supports both the high-level FastMCP API and the low-level `mcp.server.lowlevel.Server` API. Sentry is also OpenTelemetry-compatible, so if your MCP server library follows the OpenTelemetry semantic conventions for MCP, spans will show up in the dashboard.

**Which server frameworks work with MCP monitoring?**

Any Node.js server framework works, including Express, Hono, and Fastify. For Python, any ASGI or WSGI framework that runs alongside your MCP server will work. The instrumentation wraps the MCP server itself, not the HTTP framework.

**Why don't I see tool inputs and outputs in my traces?**

Sentry treats tool call arguments and results as sensitive data. In JavaScript SDK v11 and newer, they are recorded by default, so check that you haven't set `recordInputs: false` or `recordOutputs: false` in the `wrapMcpServerWithSentry` options, or turned them off with `dataCollection.genAI` in your Sentry init config. On v10, pass `recordInputs: true` and `recordOutputs: true` to `wrapMcpServerWithSentry`. For Python, set `send_default_pii=True`.

**Does this work with MCP servers using SSE transport?**

Yes. Sentry captures transport type metadata (Streamable HTTP, SSE, stdio, or custom transports) and displays the distribution on the MCP Dashboard. The instrumentation works regardless of which transport your server uses.

**Is there additional cost for MCP monitoring?**

MCP monitoring uses Sentry's tracing and error products. Tool calls, resource reads, and prompt retrievals are captured as spans within traces, so they count toward your existing tracing quota. Errors captured from MCP operations count toward your error quota.

## Next Steps

- [Set up the Sentry MCP server for debugging](https://mcp.sentry.dev/): Connect your IDE or LLM client to Sentry's own MCP server so your AI coding assistant can pull in errors, issues, and Seer analysis.

- [Explore AI observability](https://sentry.io/solutions/ai-observability/): Monitor your broader AI and LLM stack: track token usage, model invocations, and agent behavior alongside your MCP server.

- [Configure alerts](https://docs.sentry.io/product/monitors-and-alerts/alerts/): Get notified when tool error rates spike or latency crosses a threshold so you can fix issues before users notice.

---

*Source: [sentry.io/cookbook/monitor-mcp-server/](https://sentry.io/cookbook/monitor-mcp-server/)*