selfhosted-sentry-mcp

MCP server that gives AI coding agents token-efficient access to a self-hosted Sentry instance.

Why this exists

A single Sentry event endpoint can return well over 100,000 tokens — more than most models can hold, let alone reason about. Pointing an agent at the raw Sentry API usually ends in a blown context window.

This server is built around that problem:

• Compact by default. get_sentry_issue returns essential fields only; list_issue_events, list_error_events and get_release_details return summaries unless you pass full: true. get_sentry_event_details returns 5 prioritized entries by default and strips heavy blocks (sdk, packages, contexts, user, request, environment), flagging each removal.

• A token budget. List and detail tools measure their responses against a 50,000-token budget (MAX_TOKENS in src/config.ts) and truncate oversized ones with a hint instead of dumping them. The budget is a backstop, not a guarantee — narrow with filters, grep_pattern and pagination rather than relying on it.

• A refusal path. If raw_sentry_api would return more than 50,000 tokens and you did not pass a grep_pattern, it refuses and returns grep suggestions rather than flooding the conversation.

• Filters on the way out. Whitelist/blacklist field selection, regex grep, and stack-frame truncation — see FILTERING.md.

• Purpose-built extractors. get_stack_frames, list_breadcrumbs and check_dsym_status pull the debugging signal out of an event so the agent never sees the surrounding noise.

Related MCP server: Sentry MCP Server

Quickstart

Node.js 20+ and a self-hosted Sentry instance (Sentry SaaS also works if the token and org slug are valid).

1. Create a Sentry auth token

Settings → Auth Tokens → Create New Token.

For read-only use, select event:read, org:read, project:read, team:read and project:releases. Add event:write only if you want the four write tools.

Which scope each tool needs: Token scopes.

2. Find your org slug

Settings → General in your organization, or read it out of the URL: https://your-sentry.com/organizations/[slug]/.

3. Install

Use 1.2.0 or later. Every earlier version is deprecated: its raw_sentry_api accepted absolute URLs and sent your Sentry auth token to them, and it has no SENTRY_READ_ONLY. If you ran an earlier version with an agent that reads Sentry data, rotate the token. The examples use selfhosted-sentry-mcp@latest so npx checks for the newest release instead of reusing an older copy from its cache. Check what you have with npm ls -g selfhosted-sentry-mcp.

Nothing to install. The recommended setup runs the published package through npx straight from your MCP client config — skip to Client configuration.

To install it globally anyway:

npm install -g selfhosted-sentry-mcp@latest

From source:

git clone https://github.com/HieuAnh87/sentry-selfhosted-mcp.git
cd sentry-selfhosted-mcp
npm install
npm run build

The npm package is selfhosted-sentry-mcp. The GitHub repository is HieuAnh87/sentry-selfhosted-mcp — the two names are transposed. sentry-selfhosted-mcp on npm is an unrelated package by a different maintainer; do not install it and do not give it your token.

Configuration

Environment variables

The server validates the three required variables at startup and exits immediately if any is missing or if SENTRY_URL is not a valid URL.

What SENTRY_READ_ONLY=true blocks

Accepted truthy values are true and 1 (case-insensitive). Anything else, including unset, leaves the server writable. When enabled, the startup line on stderr ends with (read-only).

Token scopes

Sentry's scope namespaces are org:*, project:*, team:*, member:* and event:*. There is no issue:* or comment:* scope — issue and comment endpoints live under event:*.

Read-only setup — covers 24 of the 28 tools (everything except the four write tools):

Add only if you want the write tools:

raw_sentry_api is bounded only by the token: it can call any endpoint your scopes permit, with GET, POST, PUT or DELETE. Scope the token to what you actually need — see SECURITY.md.

Client configuration

Where the config file goes:

Option 1: npx (simplest)

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "selfhosted-sentry-mcp@latest"],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug",
        "SENTRY_READ_ONLY": "true"
      }
    }
  }
}

For Claude Code's .mcp.json you may also add "type": "stdio" alongside command.

SENTRY_READ_ONLY needs 1.2.0 or later; earlier versions ignore it silently — see the version note.

To register it at user scope instead, without writing a config file by hand:

claude mcp add --env SENTRY_URL=https://your-sentry-instance.com \
  --env SENTRY_AUTH_TOKEN=your-auth-token \
  --env SENTRY_ORG_SLUG=your-org-slug \
  --env SENTRY_READ_ONLY=true \
  --transport stdio --scope user sentry \
  -- npx -y selfhosted-sentry-mcp@latest

Option 2: global npm install

{
  "mcpServers": {
    "sentry": {
      "command": "selfhosted-sentry-mcp",
      "args": [],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

Option 3: local source build

{
  "mcpServers": {
    "sentry": {
      "command": "node",
      "args": ["<full/path/to/sentry-selfhosted-mcp/build/index.js>"],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug"
      }
    }
  }
}

These files contain a live Sentry token in plaintext. Keep them out of version control — see SECURITY.md.

Verify it works

Confirm the server starts and lists its tools before wiring it into a client:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | \
  SENTRY_URL=https://your-sentry-instance.com \
  SENTRY_AUTH_TOKEN=your-auth-token \
  SENTRY_ORG_SLUG=your-org-slug \
  npx -y selfhosted-sentry-mcp@latest

You should see a JSON response listing 28 tools, plus a startup line on stderr naming your org slug and Sentry URL. (Fewer than 28 means an outdated version — see the version note. For a source build, replace npx -y selfhosted-sentry-mcp@latest with node build/index.js.)

Self-hosted Sentry MCP server v… running for org "your-org-slug" at https://your-sentry-instance.com

If the process exits instead, one of the three required environment variables is missing or SENTRY_URL is malformed.

Or drive it interactively with the MCP inspector:

npx @modelcontextprotocol/inspector npx -y selfhosted-sentry-mcp@latest

Usage

Once the server is registered, talk to your agent normally. Prompts that map cleanly onto these tools:

• "List unresolved production issues in the checkout project, most frequent first." → list_issues with query: "is:unresolved environment:production", sort: "freq"

• "Show me the in-app stack frames for event abc123 in apple-ios." → get_stack_frames with in_app_only: true

• "What happened right before issue 5217 crashed?" → list_issue_events with issue_id: "5217", limit: 1 to get the latest event ID, then list_breadcrumbs with that event_id and the issue's project_slug

• "Are we missing dSYMs for the iOS project?" → check_dsym_status

• "Why are issues 4821 and 4822 grouped separately?" → get_issue_hashes and get_grouping_config

• "Which OS versions does issue 5217 affect?" → get_issue_tags, then get_issue_tag_values with tag_key: "os.name"

If a response comes back truncated, narrow it rather than asking for more — pass entry_type, limit, grep_pattern or max_stack_frames, or page with cursor. See Reducing response size.

Tools

28 tools across 8 categories. Parameters are required unless marked optional.

WRITE marks the five tools that can modify Sentry. Under SENTRY_READ_ONLY=true the four dedicated write tools are hidden from the tool list and refused if called anyway, while raw_sentry_api stays available with GET only. Every tool also carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint), so clients can decide which calls need confirmation — see Configuration.

Issue IDs. Every issue_id parameter accepts either a numeric ID (5217) or a short ID as shown in the Sentry UI (PROJ-1A2). get_sentry_issue also accepts a full issue URL.

Pagination. Tools that take a cursor return, when Sentry has more results, a second text content block after the main result:

{"next_cursor": "0:25:0", "has_more": true, "hint": "More results exist. Call this tool again with cursor set to next_cursor."}

Call the same tool again with cursor set to next_cursor to get the next page. When there is no further page, the block is absent. The first block keeps its existing shape, so clients that only read content[0] are unaffected.

Write tools act on real data. bulk_update_issues requires a non-empty query or an issue_ids list and refuses to run without one — with no selection, Sentry would apply the change to every unresolved issue in the project (up to 1000). A broad query can still match hundreds of issues; check it with list_sentry_issues first. merge_issues cannot be undone.

Issue tools

Event tools

Release tools

Organization tools

Advanced tools

Attachment and feedback tools

Account tools

Raw API

Reducing response size

get_sentry_issue accepts five parameters that control response size — include_latest_event, include_fields, exclude_fields, max_stack_frames and grep_pattern — that exist specifically to keep large issues inside the token budget. max_stack_frames and any latest_event.* filter only have something to act on when include_latest_event: true is set.

FILTERING.md documents all of them with worked examples, including the recommended escalation order when a response is still too big.

Quick reference for the other tools:

Docker

Build:

docker build -t selfhosted-sentry-mcp:latest .

The Docker image builds from your checkout, so it includes SENTRY_READ_ONLY and all 28 tools regardless of what is published on npm.

Client config:

{
  "mcpServers": {
    "sentry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "SENTRY_URL",
        "-e", "SENTRY_AUTH_TOKEN",
        "-e", "SENTRY_ORG_SLUG",
        "-e", "SENTRY_READ_ONLY",
        "selfhosted-sentry-mcp:latest"
      ],
      "env": {
        "SENTRY_URL": "https://your-sentry-instance.com",
        "SENTRY_AUTH_TOKEN": "your-auth-token",
        "SENTRY_ORG_SLUG": "your-org-slug",
        "SENTRY_READ_ONLY": "true"
      }
    }
  }
}

SENTRY_READ_ONLY is optional: drop both of its lines to expose the write tools. Outside an MCP config, the equivalent docker run flag is -e SENTRY_READ_ONLY=true.

Using an env file keeps the token out of the config file entirely:

# /path/to/.env
SENTRY_URL=https://your-sentry-instance.com
SENTRY_AUTH_TOKEN=your-auth-token
SENTRY_ORG_SLUG=your-org-slug
# Optional: block write tools. Keep comments on their own line;
# Docker does not strip trailing "# ..." from values.
SENTRY_READ_ONLY=true

{
  "mcpServers": {
    "sentry": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/.env",
        "selfhosted-sentry-mcp:latest"
      ]
    }
  }
}

Verify the image:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | docker run -i --rm \
  -e SENTRY_URL=https://example.com \
  -e SENTRY_AUTH_TOKEN=test \
  -e SENTRY_ORG_SLUG=test \
  selfhosted-sentry-mcp:latest

Development

npm install     # runs the build via the prepare hook
npm run build
npm test

See CONTRIBUTING.md for the full workflow. In short: src/** is the source of truth, build/** is generated and must never be edited by hand, and tool names and input schemas are a public contract.

Run the MCP inspector against a local build:

npx @modelcontextprotocol/inspector build/index.js

Security

The server holds a live Sentry API token supplied as a plaintext environment variable, usually inside a config file that is easy to commit by accident.

Read SECURITY.md before deploying it. It covers least-privilege token scoping, why raw_sentry_api bypasses least-privilege reasoning, the SENTRY_READ_ONLY switch, keeping tokens out of version control, and how to report a vulnerability.

Troubleshooting

Server not starting, or tools not showing

• Verify SENTRY_URL, SENTRY_AUTH_TOKEN and SENTRY_ORG_SLUG are all set. The server exits at startup if any is missing.

• Confirm SENTRY_URL parses as a URL (include the scheme: https://…).

• Check Node.js 20+: node --version.

• On Claude Code, confirm the config is in .mcp.json or was added with claude mcp add. An mcpServers block in settings.json is ignored — the server will never load and there is no error.

"Unauthorized" or "403"

• The token is invalid, expired, or lacks the scope for that endpoint. Match the failing tool against the scope table.

• Confirm the token belongs to the organization in SENTRY_ORG_SLUG.

"Tool is disabled: server is running in read-only mode"

• Expected if SENTRY_READ_ONLY is set to true or 1. Unset it to restore write access. The startup line on stderr ends with (read-only) when the mode is active.

"Project not found"

• Confirm the slug exists; run list_sentry_projects to see the valid ones.

Empty or truncated responses

• Use limit and entry_type on get_sentry_event_details.

• Use grep_pattern on raw_sentry_api for large endpoints.

• See Reducing response size.

Docker container exits immediately

• All three required variables must reach the container. With -e VAR (no value) the variable must exist in your shell; otherwise use --env-file.

• Check docker logs <container-id>.

FAQ

Is this self-hosted only? It targets self-hosted Sentry, but works against Sentry SaaS when the token and org slug are valid.

Why use raw_sentry_api when typed tools exist? For endpoints the typed tools do not cover. It returns unfiltered JSON, so pass grep_pattern on anything event-shaped — above 50,000 tokens it refuses outright without one.

Can I stop the agent from modifying Sentry? Set SENTRY_READ_ONLY=true (requires 1.2.0 or later — see the version note). That hides and refuses the four mutating tools and restricts raw_sentry_api to GET. For a stronger guarantee, issue a token without event:write — the env var stops an agent from calling the tool, the scope stops the credential from being usable at all.

Does it work with Sentry's newer API versions? Yes, for the versions in use today. Sentry has shipped only one public web API version — /api/0/ — and every endpoint here is composed against it in src/api/client.ts. If Sentry ever publishes a /api/1/, this server would need updating.

License

MIT — see LICENSE.