getsentry/sentry-mcp: a Sentry MCP server built for coding agents

What getsentry/sentry-mcp is for, and who it is not for

The README opens with a scoping statement that is unusual for a project of this kind: the service is "primarily designed for human-in-the-loop coding agents", and tool selection follows developer workflows and debugging rather than general Sentry coverage. That sentence is the whole design brief. This is not an MCP wrapper around every Sentry endpoint. It is a middleware layer in front of the upstream Sentry API, tuned so an assistant can pull an issue, read a stack trace, or look at events while a developer stays in the loop.

The audience follows from that. If you debug inside Cursor, Claude Code, VS Code or Codex and you keep a browser tab open on Sentry to copy stack traces by hand, this removes that step. If you want an agent to administer projects, rotate keys, manage alert rules or bulk-edit issues, the README does not promise that surface, and the tool set is deliberately narrower. The project also states it is based on Cloudflare's work on remote MCP servers, which explains the deployment shape: a hosted worker at mcp.sentry.dev plus a stdio package for local and self-hosted use.

Remote worker, stdio package, and where the token is validated

There are two transports, and they behave differently enough that the choice matters.

The remote transport is the deployed service. Clients that can send custom HTTP headers pass an upstream Sentry token with the Authorization header set to Sentry-Bearer. The README is explicit about why the prefix is not plain Bearer: Bearer is reserved for MCP OAuth access tokens. With Sentry-Bearer, the worker does not store, validate, exchange or refresh the upstream token. It forwards the token through the same Sentry API calls used by OAuth-backed sessions, and the client or upstream provider stays responsible for token lifetime and refresh. That is a meaningful boundary. The hosted worker becomes a pass-through for your credential rather than a custodian of it, and token rotation is your problem, not the service's.

The stdio transport runs locally and is described as a work in progress, but it is the easiest path to a self-hosted Sentry install. It takes the token as a command line argument and talks to the same upstream API. Because it runs on your machine, there is no Cloudflare hop, and the README positions it as the adaptation route for self-hosted deployments.

On top of the transport sits a skill layer. Direct remote auth defaults to all active MCP skills, and you can narrow the exposed tools with a query parameter such as ?skills=inspect,triage or ?disable-skills=seer. The stdio path exposes the same idea as flags. This is the mechanism that keeps a self-hosted instance from advertising tools its backend cannot serve.

Installing sentry-mcp in Claude Code and running the stdio server

The README gives a plugin path for Claude Code that installs a subagent rather than a bare server. The first command registers the repository as a plugin marketplace, the second installs the plugin. According to the README, this provides a sentry-mcp subagent that Claude delegates to automatically when you ask about Sentry errors, issues, traces or performance.

claude plugin marketplace add getsentry/sentry-mcp
claude plugin install sentry-mcp@sentry-mcp

There is a second plugin, sentry-mcp@sentry-mcp-experimental, described as carrying forward-looking tool variants and features. Install it the same way if you want those, and expect the README's framing to apply: forward-looking means not the default set.

For the stdio transport you need a Sentry user auth token. The README lists the scopes as of writing: org:read, project:read, project:write, team:read, team:write and event:write. Then launch the package with npx, passing the token as --access-token.

npx @sentry/mcp-server@latest --access-token=sentry-user-token

For a self-hosted deployment, add --host with the hostname only, for example --host=sentry.example.com. If the deployment only exposes plain HTTP, add --insecure-http as well.

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.internal:9000 --insecure-http

If a feature such as Seer is not available on your instance, disable the skill so unsupported tools are not exposed. The README shows the flag combined with --host.

npx @sentry/mcp-server@latest --access-token=TOKEN --host=sentry.example.com --disable-skills=seer

The equivalent client configuration uses npx as the command and passes the token and provider keys through env. The README's example sets SENTRY_ACCESS_TOKEN, EMBEDDED_AGENT_PROVIDER and the matching provider key.

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "EMBEDDED_AGENT_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

If you leave the host variable unset, the README states the CLI automatically targets Sentry SaaS, so only set the override for self-hosted instances. For a self-hosted instance without Seer, the README's second example adds SENTRY_HOST and MCP_DISABLE_SKILLS alongside the token.

{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "your-token",
        "SENTRY_HOST": "sentry.example.com",
        "MCP_DISABLE_SKILLS": "seer"
      }
    }
  }
}

To check the server without wiring up an assistant, the repository ships an inspector script. The README says to run pnpm inspector, enter the MCP server URL (http://localhost:5173) and connect, which triggers the authentication flow.

pnpm inspector

One note from the README that saves confusion: if the OAuth flow misbehaves on 127.0.0.1, use localhost instead and visit http://localhost:6274.

The AI search tools need an LLM provider, and that is a real dependency

The tools named search_events, search_issues and their relatives do not query Sentry directly. They translate natural language into Sentry's query syntax using an LLM provider: OpenAI, Azure OpenAI, Anthropic or OpenRouter. The README states the consequence plainly. Without a configured provider, those specific tools are unavailable, but all other tools function normally.

That is a split service, and it is worth planning for. A team that wants natural language search has to hold a second vendor key and accept that queries about production errors pass through that provider for translation. The README also warns that auto-detection based on API keys alone is deprecated and will be removed in a future release, so set EMBEDDED_AGENT_PROVIDER explicitly even when only one key is present. When multiple provider keys are set, that variable is required to pick between them. OpenRouter users get two optional knobs: OPENROUTER_MODEL, which defaults to openai/gpt-5.6-luna, and OPENROUTER_REASONING_EFFORT, which defaults to high. The .env.example file in the repository shows OPENROUTER_API_KEY as the default example key and leaves OPENAI_API_KEY commented out.

Where sentry-mcp is the wrong tool

The stdio transport is labelled a work in progress by the README itself, and that label is the first limitation to take seriously. If you are building a production automation pipeline against a self-hosted Sentry, you are building on a path the maintainers describe as still in progress, not on the hosted service they point people to at mcp.sentry.dev.

The second limitation is scope. The README's opening paragraph rules out general-purpose Sentry coverage on purpose. Tool selection follows coding and debugging workflows. Anyone expecting an MCP surface that mirrors the Sentry API will find the tool list narrower than the API, and the README does not document a way to extend it from the client side.

The third is self-hosted feature parity. The README notes that some features, Seer among them, may not be available on self-hosted instances, and the remedy it offers is subtraction: disable the skill so unsupported tools are not exposed. That is a reasonable guard, but it means a self-hosted setup is not feature-identical to the SaaS path, and the README does not enumerate which other skills fall into the same category. If a specific capability matters, check it against your instance before you plan around it.

Finally, the remote transport with Sentry-Bearer puts token lifetime management on you. The worker does not refresh the upstream token. An expired token surfaces as failed Sentry calls inside the assistant, which is a harder failure to read than a login prompt.

How this differs from a plain Sentry API client or a general MCP server

The obvious alternative is calling the Sentry API directly from your own script or from a custom tool. The difference is where the translation lives. With a direct client you own query construction, pagination, error handling and the mapping from a developer's question to an API call. With sentry-mcp, the server owns the tool definitions and, for the search tools, owns the natural language to Sentry query translation through the configured LLM provider. You trade control over the call shape for not writing it.

A general-purpose MCP server is the other comparison, and it is the one the README pre-empts. A general server aims to expose as much of an upstream product as possible. This project does the opposite: it narrows to debugging workflows and says so in the first paragraph. If your agent needs broad administrative reach across Sentry, a narrower server is a constraint, not a feature. If your agent needs to answer "what broke in this release and why", the narrowing is what keeps the tool list small enough for a model to choose from.

The self-hosted stdio path also competes with simply running your own MCP server against your internal Sentry. The README's argument for using theirs is the skill layer and the existing tool definitions, plus the --host and --insecure-http flags that handle internal deployments. The argument against is the work-in-progress label.

Maintenance, licence and what the repository tells you about upgrade cost

The last push to the default branch was on 2026-09-10, and the most recent release listed is 0.39.0 from 2026-08-27, preceded by 0.38.0 the day before and 0.37.0 on 2026-07-02. The 0.x version line and the cadence of releases suggest the interface is still moving. The repository is not archived.

The package.json declares "license": "FSL-1.1-ALv2". That is the Functional Source License with an Apache 2.0 future licence, which is a source-available licence rather than a classic open source one, and it is worth reading before you build a product on top of the code. The GitHub metadata for the repository reports NOASSERTION, so the two sources do not agree on a label. I am not a lawyer and this is not legal advice; if the distinction matters to your organisation, read LICENSE.md in the repository and get your own review.

Upgrade cost is mostly the tool surface. The repository has a check:generated script that regenerates toolDefinitions.json and skillDefinitions.json and diffs them, which tells you the tool and skill definitions are generated artifacts rather than hand-written ones. In practice that means the exposed tools can change between releases without a corresponding change in your client config, and the version pin @latest in the README's npx command will track those changes for you whether you want it to or not. Pinning a version is the conservative choice if you depend on a specific tool being present.

Editorial conclusion

Adopt getsentry/sentry-mcp if your debugging loop already runs inside Cursor, Claude Code, VS Code or Codex and you want Sentry issues and traces reachable from the same prompt. Skip it if you need a full Sentry administration API, or if you cannot issue an LLM provider key, because the AI search tools stay unavailable without one. Before rolling it out, verify the exact token scopes against your Sentry organization, and check whether your self-hosted instance supports Seer, since the README notes some features may not be available there.

Frequently asked questions

Official sources

1. getsentry/sentry-mcp on GitHub
2. Issues
3. Project website
4. README
5. Releases