sentry-selfhosted-mcp: Instructions file for Codex

selfhosted-sentry-mcp

TypeScript MCP server for self-hosted Sentry triage/debug workflows.

Commands

# Install deps
npm install

# Build TypeScript to ./build and set executable bit
npm run build

# Watch mode during source edits
npm run watch

# Run MCP inspector against built server
npm run inspector

# Test full suite (Node test runner)
npm test

# Test smoke flow only
npm run test:smoke

# Run one test file
node --test test/tools.test.js

# Docker image build
docker build -t selfhosted-sentry-mcp:latest .   # not sentry-selfhosted-mcp: that name is an unrelated npm package

Boundaries

• Do not commit real SENTRY_AUTH_TOKEN or real Sentry URLs in docs/examples.
• Do not edit build/** directly; source of truth is src/**.
• Keep MCP tool names and input schemas backward compatible unless explicitly requested.
• Avoid widening output payloads without grep/filter controls (token bloat risk).

Where to look

Conventions (deviations only)

• ESM imports use explicit .js extension in TS source (Node16 module resolution).
• Entry point is intentionally thin: src/index.ts only imports ./server.js for compatibility.
• Raw API tool warns on large event payloads and supports grep_pattern; preserve this behavior.
• Tool results may have more than one content block: the main payload first, then an optional pagination block. Don't assume content.length === 1, and don't fold the cursor into content[0].
• Bulk issue mutations must carry an id or query selection in the URL; selectorParams in src/api/client.ts refuses an empty one. Never bypass it — Sentry applies an unselected bulk update to every unresolved issue in the project.