Sentry MCP Server Setup for Error Monitoring

Sentry MCP Server Setup for Error Monitoring

Software bugs and unhandled runtime exceptions are an inevitable byproduct of continuous software deployment. When production incidents occur, engineering teams spend valuable engineering cycles navigating error tracking dashboards, correlating stack traces, identifying culprit pull requests, and formulating regression fixes.

The Sentry Model Context Protocol (MCP) server transforms this reactive workflow into an agentic, automated debugging loop. By bridging local AI clients directly with Sentry's developer APIs over standard JSON-RPC 2.0 stdio streams, the server grants artificial intelligence models real-time visibility into production exceptions. Autonomous agents can triage newly surfaced issues, inspect exact call stacks across service boundaries, cross-reference source code in your local repository, and draft targeted pull requests before human engineers finish reading incident alerts.

1. Problem Statement and Architecture

Connecting autonomous coding agents to observability platforms presents notable operational hurdles:

1. ▸Dashboard Context Switching: Engineers traditionally copy stack traces, exception messages, and environment breadcrumbs from web consoles into chat windows, losing crucial surrounding execution context.
2. ▸Access Control and Scoping: Production telemetry contains sensitive user identifiers, internal URLs, and environmental metadata. Access to error telemetry must respect strict organizational scoping and principle-of-least-privilege read permissions.
3. ▸High-Frequency Exception Noise: Production services experience transient spikes, flapped connections, and noisy third-party client crashes. Agents require structured search filters (is:unresolved, level:error, timesSeen:>10) to isolate substantive regressions from background noise.

+-----------------------------------------------------------------------------------+
|                              Client Architecture                                  |
|                                                                                   |
|  +--------------------+        JSON-RPC 2.0 (stdio)        +-------------------+  |
|  |  Claude / Cursor   | <================================> | mcp-server-sentry |  |
|  +--------------------+                                    +---------+---------+  |
+----------------------------------------------------------------------|------------+
                                                                       | HTTPS REST API
                                                                       | Bearer Token
                                                                       v
                                                             +-------------------+
                                                             | Sentry Cloud /    |
                                                             | Self-Hosted API   |
                                                             +-------------------+

The mcp-server-sentry daemon operates locally as an out-of-process Python service. When an AI client transmits an MCP tool request, the server signs an authorized REST call to Sentry's /api/0/ endpoints, filters the payload for agent readability, and returns sanitized issue summaries, event breadcrumbs, and symbolicated stack traces.

2. Prerequisites and Environment Matrix

The Sentry server is distributed through the official PyPI registry under mcp-server-sentry. It requires Python 3.10+ and a valid Sentry User Auth Token with appropriate organization read permissions.

Generating a Scoped Sentry Token

1. ▸Navigate to Sentry Settings -> Account -> API -> User Auth Tokens.
2. ▸Click Create New Token.
3. ▸Assign the following least-privilege scopes:
   • ▸project:read — Discover available organizations and repositories.
   • ▸event:read — Retrieve exception stack traces and breadcrumbs.
   • ▸issue:read — Query unresolved error clusters and event frequencies.
4. ▸Copy the generated authorization token (sntrys_...).

3. Multi-Host Configuration Snippets

The server reads authentication credentials via command-line arguments or environment variables. Below are verified configurations across major development hosts.

Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "sentry": {
      "command": "uvx",
      "args": ["mcp-server-sentry", "--auth-token", "sntrys_YOUR_AUTH_TOKEN_HERE"]
    }
  }
}

Cursor IDE

In .cursor/mcp.json or your global workspace configuration:

{
  "mcpServers": {
    "sentry": {
      "command": "uvx",
      "args": ["mcp-server-sentry"],
      "env": {
        "SENTRY_AUTH_TOKEN": "sntrys_YOUR_AUTH_TOKEN_HERE"
      }
    }
  }
}

OpenAI Codex CLI

In ~/.codex/config.toml:

[mcp_servers.sentry]
command = "uvx"
args = ["mcp-server-sentry", "--auth-token", "sntrys_YOUR_AUTH_TOKEN_HERE"]

For self-hosted instances, specify the custom domain by appending --base-url <YOUR_CUSTOM_SENTRY_URL> to the argument array.

4. Step-by-Step Tool Discovery and Invocation

During initialization, the server advertises its core diagnostic tools to the host:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_issues",
        "description": "List issues for a project in Sentry with filtering options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "issue_status": {
              "type": "string",
              "enum": ["resolved", "unresolved", "ignored"],
              "default": "unresolved"
            },
            "query": {
              "type": "string",
              "description": "Sentry search query string (e.g. 'is:unresolved level:error')"
            }
          }
        }
      },
      {
        "name": "get_issue_details",
        "description": "Retrieve comprehensive details and stack traces for a specific issue ID.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "issue_id": { "type": "string", "description": "Numeric Sentry issue ID" }
          },
          "required": ["issue_id"]
        }
      }
    ]
  }
}

Tool Invocation Wire Frame

When a developer requests: "Find the most frequent unresolved backend error from the last 24 hours", the AI client initiates:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_issues",
    "arguments": {
      "issue_status": "unresolved",
      "query": "is:unresolved level:error sort:freq"
    }
  }
}

The server queries Sentry's issue index and returns structured error records:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found Issue 5829104:\nTitle: NullReferenceException: Object reference not set to an instance\nCulprit: PaymentGateway.ProcessWebhook\nEvents: 421 | Users Affected: 38\nFirst Seen: 2026-10-08 | Status: Unresolved"
      }
    ],
    "isError": false
  }
}

5. Common Errors and Production Troubleshooting

1. HTTP 401 Unauthorized or Invalid Token

• ▸Symptom: Server logs show Authentication credentials were not provided or 401 Unauthorized.
• ▸Root Cause: The token string was improperly escaped, expired, or lacked the required organization-level permission scopes.
• ▸Solution: Regenerate the token in Sentry Account Settings. Ensure the token begins with the modern prefix (sntrys_) and that the organization's single sign-on (SSO) authorization policy has approved API token access.

2. HTTP 429 Too Many Requests During Bulk Scans

• ▸Symptom: The agent halts mid-analysis with rate limit errors.
• ▸Root Cause: Iterative agent loops scanning dozens of issue payloads consecutively exceed Sentry's standard per-minute burst rate limits.
• ▸Solution: Restrict agent prompts to query specific issue identifiers or add sorting limiters (e.g., limit=5) rather than unconstrained batch queries.

3. Missing Stack Traces on Minified Production Bundles

• ▸Symptom: get_issue_details returns unhelpful minified variable names like a(b, c) at app.min.js:1:42.
• ▸Root Cause: Production source maps have not been uploaded to Sentry for the corresponding release version.
• ▸Solution: Ensure your build pipeline uploads release source maps via the @sentry/webpack-plugin, @sentry/vite-plugin, or the Sentry CLI during continuous integration builds.

6. External Citations and Security Guardrails

Connecting LLMs to production error tracking requires rigorous telemetry protection:

1. ▸Personally Identifiable Information (PII): Configure Sentry's server-side Data Scrubbing rules to redact email addresses, IP addresses, credit cards, and authorization headers before events are recorded.
2. ▸Read-Only Scopes: Avoid assigning issue:delete or administrative write permissions to general development agent tokens.
3. ▸Verified Registry Distribution: Always consume mcp-server-sentry from the official PyPI repository.

• ▸PyPI mcp-server-sentry Package (opens in a new tab)
• ▸Official Model Context Protocol GitHub Repository (opens in a new tab)
• ▸Official Sentry REST API Documentation (opens in a new tab)