Sentry MCP

1# sentry-mcp
2 
3Sentry's MCP service is primarily designed for human-in-the-loop coding agents. Our tool selection and priorities are focused on developer workflows and debugging use cases, rather than providing a general-purpose MCP server for all Sentry functionality.
4 
5This remote MCP server acts as middleware to the upstream Sentry API, optimized for coding assistants like Cursor, Claude Code, and similar development tools. It's based on [Cloudflare's work towards remote MCPs](https://blog.cloudflare.com/remote-model-context-protocol-servers-mcp/).
6 
7## Getting Started
8 
9You'll find everything you need to know by visiting the deployed service in production:
10 
11<https://mcp.sentry.dev>
12 
13If you're looking to contribute, learn how it works, or to run this for self-hosted Sentry, continue below.
14 
15### Claude Code Plugin
16 
17Install as a Claude Code plugin for automatic subagent delegation:
18 
19```shell
20claude plugin marketplace add getsentry/sentry-mcp
21claude plugin install sentry-mcp@sentry-mcp
22```
23 
24This provides a `sentry-mcp` subagent that Claude automatically delegates to when you ask about Sentry errors, issues, traces, or performance.
25 
26For experimental features:
27 
28```shell
29claude plugin install sentry-mcp@sentry-mcp-experimental
30```
31 
32### Stdio vs Remote
33 
34While this repository is focused on acting as an MCP service, we also support a `stdio` transport. This is still a work in progress, but is the easiest way to adapt run the MCP against a self-hosted Sentry install.
35 
36**Note:** The AI-powered search tools (`search_events`, `search_issues`, etc.) require an LLM provider (OpenAI or Anthropic). These tools use natural language processing to translate queries into Sentry's query syntax. Without a configured provider, these specific tools will be unavailable, but all other tools will function normally.
37 
38To utilize the `stdio` transport, you'll need to create an User Auth Token in Sentry with the necessary scopes. As of writing this is:
39 
40```
41org:read
42project:read
43project:write
44team:read
45team:write
46event:write
47```
48 
49Launch the transport:
50 
51```shell
52npx @sentry/mcp-server@latest --access-token=sentry-user-token
53```
54 
55Need to connect to a self-hosted deployment? Add <code>--host</code> (hostname
56only, e.g. <code>--host=sentry.example.com</code>) when you run the command.
57 
58Some features (like Seer) may not be available on self-hosted instances. You can
59disable specific skills to prevent unsupported tools from being exposed:
60 
61```shell
62npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.example.com --disable-skills=seer
63```
64 
65#### Environment Variables
66 
67```shell
68SENTRY_ACCESS_TOKEN=         # Required: Your Sentry auth token
69 
70# LLM Provider Configuration (required for AI-powered search tools)
71EMBEDDED_AGENT_PROVIDER=     # Required: 'openai' or 'anthropic'
72OPENAI_API_KEY=              # Required if using OpenAI
73ANTHROPIC_API_KEY=           # Required if using Anthropic
74 
75# Optional overrides
76SENTRY_HOST=                 # For self-hosted deployments
77MCP_DISABLE_SKILLS=          # Disable specific skills (comma-separated, e.g. 'seer')
78```
79 
80**Important:** Always set `EMBEDDED_AGENT_PROVIDER` to explicitly specify your LLM provider. Auto-detection based on API keys alone is deprecated and will be removed in a future release. See [docs/embedded-agents.md](docs/embedded-agents.md) for detailed configuration options.
81 
82#### Example MCP Configuration
83 
84```json
85{
86  "mcpServers": {
87    "sentry": {
88      "command": "npx",
89      "args": ["@sentry/mcp-server"],
90      "env": {
91        "SENTRY_ACCESS_TOKEN": "your-token",
92        "EMBEDDED_AGENT_PROVIDER": "openai",
93        "OPENAI_API_KEY": "sk-..."
94      }
95    }
96  }
97}
98```
99 
100If you leave the host variable unset, the CLI automatically targets the Sentry
101SaaS service. Only set the override when you operate self-hosted Sentry.
102 
103For self-hosted instances that don't support Seer:
104 
105```json
106{
107  "mcpServers": {
108    "sentry": {
109      "command": "npx",
110      "args": ["@sentry/mcp-server"],
111      "env": {
112        "SENTRY_ACCESS_TOKEN": "your-token",
113        "SENTRY_HOST": "sentry.example.com",
114        "MCP_DISABLE_SKILLS": "seer"
115      }
116    }
117  }
118}
119```
120 
121### MCP Inspector
122 
123MCP includes an [Inspector](https://modelcontextprotocol.io/docs/tools/inspector), to easily test the service:
124 
125```shell
126pnpm inspector
127```
128 
129Enter the MCP server URL (<http://localhost:5173>) and hit connect. This should trigger the authentication flow for you.
130 
131Note: If you have issues with your OAuth flow when accessing the inspector on `127.0.0.1`, try using `localhost` instead by visiting `http://localhost:6274`.
132 
133## Local Development
134 
135To contribute changes, you'll need to set up your local environment:
136 
1371. **Set up environment and agent skills:**
138 
139   ```shell
140   make setup-env  # Creates .env files and installs shared agent skills
141   ```
142 
143   This also runs `npx @sentry/dotagents install` to install shared skills from [getsentry/skills](https://github.com/getsentry/skills) into `.agents/skills/` (symlinked into `.claude/skills` and `.cursor/skills`). If you need to update skills later, run it directly:
144 
145   ```shell
146   npx @sentry/dotagents install
147   ```
148 
1492. **Create an OAuth App in Sentry** (Settings => API => [Applications](https://sentry.io/settings/account/api/applications/)):
150 
151   - Homepage URL: `http://localhost:5173`
152   - Authorized Redirect URIs: `http://localhost:5173/oauth/callback`
153   - Note your Client ID and generate a Client secret
154 
1553. **Configure your credentials:**
156 
157   - Edit `.env` in the root directory and add your `OPENAI_API_KEY`
158   - Edit `packages/mcp-cloudflare/.env` and add:
159     - `SENTRY_CLIENT_ID=your_development_sentry_client_id`
160     - `SENTRY_CLIENT_SECRET=your_development_sentry_client_secret`
161     - `COOKIE_SECRET=my-super-secret-cookie`
162 
1634. **Start the development server:**
164 
165   ```shell
166   pnpm dev
167   ```
168 
169### Verify
170 
171Run the server locally to make it available at `http://localhost:5173`
172 
173```shell
174pnpm dev
175```
176 
177To test the local server, enter `http://localhost:5173/mcp` into Inspector and hit connect. Once you follow the prompts, you'll be able to "List Tools".
178 
179### Tests
180 
181There are three test suites included: unit tests, evaluations, and manual testing.
182 
183**Unit tests** can be run using:
184 
185```shell
186pnpm test
187```
188 
189**Evaluations** require a `.env` file in the project root with some config:
190 
191```shell
192# .env (in project root)
193OPENAI_API_KEY=  # Also required for AI-powered search tools in production
194```
195 
196Note: The root `.env` file provides defaults for all packages. Individual packages can have their own `.env` files to override these defaults during development.
197 
198Once that's done you can run them using:
199 
200```shell
201pnpm eval
202```
203 
204**Manual testing** (preferred for testing MCP changes):
205 
206```shell
207# Test with local dev server (default: http://localhost:5173)
208pnpm -w run cli "who am I?"
209 
210# Test agent mode (use_sentry tool only)
211pnpm -w run cli --agent "who am I?"
212 
213# Test against production
214pnpm -w run cli --mcp-host=https://mcp.sentry.dev "query"
215 
216# Test with local stdio mode (requires SENTRY_ACCESS_TOKEN)
217pnpm -w run cli --access-token=TOKEN "query"
218```
219 
220Note: The CLI defaults to `http://localhost:5173`. Override with `--mcp-host` or set `MCP_URL` environment variable.
221 
222**Comprehensive testing playbooks:**
223- **Stdio testing:** See `docs/testing-stdio.md` for complete guide on building, running, and testing the stdio implementation (IDEs, MCP Inspector)
224- **Remote testing:** See `docs/testing-remote.md` for complete guide on testing the remote server (OAuth, web UI, CLI client)
225 
226## Development Notes
227 
228### Automated Code Review
229 
230This repository uses automated code review tools (like Cursor BugBot) to help identify potential issues in pull requests. These tools provide helpful feedback and suggestions, but **we do not recommend making these checks required** as the accuracy is still evolving and can produce false positives.
231 
232The automated reviews should be treated as:
233 
234- ✅ **Helpful suggestions** to consider during code review
235- ✅ **Starting points** for discussion and improvement
236- ❌ **Not blocking requirements** for merging PRs
237- ❌ **Not replacements** for human code review
238 
239When addressing automated feedback, focus on the underlying concerns rather than strictly following every suggestion.
240 
241### Contributor Documentation
242 
243Looking to contribute or explore the full documentation map? See `CLAUDE.md` (also available as `AGENTS.md`) for contributor workflows and the complete docs index. The `docs/` folder contains the per-topic guides and tool-integrated `.md` files.
244