# Sentry MCP Server
A stateless FastMCP server for Sentry API integration, supporting multiple Sentry instances (US, EU, self-hosted) with a single deployment.
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Customer VPC │
│ │
│ ┌──────────────┐ ┌─────────────────────────────┐ │
│ │ Satellite │ ──MCP──▶│ Sentry MCP Server │ │
│ └──────────────┘ │ ┌─────────┐ ┌─────────┐ │ │
│ │ │sentryUS │ │sentryEU │ │ │
│ │ └────┬────┘ └────┬────┘ │ │
│ └───────┼───────────┼─────────┘ │
└───────────────────────────────────┼───────────┼─────────────┘
│ │
▼ ▼
sentry.io de.sentry.io
(US) (EU)
```
## Features
- **Multi-instance support**: Configure multiple Sentry accounts (US, EU, self-hosted)
- **Base tools + instance parameter**: 11 tools that work across all instances
- **Stateless HTTP**: Scales horizontally, no session state
- **Secure**: Auth tokens stored in K8s secrets, never exposed to Claude
## Tools
| Tool | Description |
|------|-------------|
| `list_sentry_instances` | Discovery - list all configured Sentry accounts |
| `find_organizations` | List organizations accessible with the token |
| `find_teams` | List teams in an organization |
| `find_projects` | List projects in an organization |
| `find_releases` | List releases in an org/project |
| `get_issue_details` | Get detailed info about a specific issue |
| `search_issues` | Search for grouped issues in a project |
| `search_issue_events` | Search events within a specific issue |
| `search_events` | Search events and perform aggregations |
| `get_trace_details` | Get trace overview and span breakdown |
| `get_event_attachment` | Download attachments from an event |
## Quick Start
### 1. Create Internal Integration in Sentry
For each Sentry organization you want to connect:
1. Go to **Settings → Developer Settings → Internal Integrations**
- US: `https://sentry.io/settings/{org}/developer-settings/`
- EU: `https://de.sentry.io/settings/{org}/developer-settings/`
2. Click **Create New Internal Integration**
3. Configure:
- **Name**: `Deeptrace MCP`
- **Scopes** (read-only):
- `org:read`
- `project:read`
- `event:read`
- `team:read`
- `member:read`
4. Click **Save** and copy the generated token (starts with `sntrys_...`)
### 2. Create Kubernetes Secrets
```bash
# US Sentry
kubectl create secret generic sentry-us-creds \
--from-literal=auth_token="sntrys_eyJ..." \
-n deeptrace
# EU Sentry
kubectl create secret generic sentry-eu-creds \
--from-literal=auth_token="sntrys_eyJ..." \
-n deeptrace
```
### 3. Deploy with Helm
Create a `values.yaml`:
```yaml
instances:
sentryUS:
enabled: true
region: "us"
orgSlug: "your-org-slug"
secretName: "sentry-us-creds"
labels:
dataResidency: "US"
description: "US customer data and services"
sentryEU:
enabled: true
region: "eu"
orgSlug: "your-org-slug-eu"
secretName: "sentry-eu-creds"
labels:
dataResidency: "EU"
description: "EU customer data (GDPR)"
```
Install:
```bash
helm install sentry-mcp ./helm/sentry-mcp \
-f values.yaml \
-n deeptrace
```
### 4. Configure Satellite
Add to your satellite's `values.yaml`:
```yaml
mcpServers:
sentryMCP:
create: true
type: mcp
connection:
url: "http://sentry-mcp.deeptrace:8080/mcp"
transport: "streamable_http"
stateless: true
auditLogging: true
domainAllowlist:
- "sentry-mcp.deeptrace"
```
## Configuration Reference
### Instance Configuration
| Field | Required | Description |
|-------|----------|-------------|
| `enabled` | No | Enable/disable instance (default: true) |
| `region` | Yes | `us`, `eu`, or `custom` |
| `orgSlug` | Yes | Sentry organization slug |
| `baseUrl` | For custom | Full URL for self-hosted Sentry |
| `secretName` | Yes | K8s secret name with `auth_token` key |
| `labels.dataResidency` | No | Data residency label (e.g., "US", "EU") |
| `labels.description` | No | Human-readable description |
| `labels.team` | No | Team that owns this instance |
| `labels.environment` | No | Environment (production, staging) |
### Self-Hosted Example
```yaml
instances:
sentrySelfHosted:
enabled: true
region: "custom"
baseUrl: "https://sentry.internal.company.com"
orgSlug: "internal"
secretName: "sentry-internal-creds"
labels:
dataResidency: "On-Premise"
description: "Self-hosted Sentry for internal services"
```
## How It Works
### Claude's Workflow
1. **Discovery**: Claude calls `list_sentry_instances()` to see available Sentry accounts
2. **Query**: Claude uses the instance name when calling other tools
3. **Multi-region**: Claude queries both instances when context is ambiguous
Example conversation:
```
User: "Find unresolved errors in the Platform team's Sentry"
Claude: I'll check the available Sentry instances first.
→ list_sentry_instances()
→ Returns: [sentryUS (US), sentryEU (EU)]
Claude: The Platform team uses the EU instance based on the labels.
→ search_issues(instance="sentryEU", query="is:unresolved level:error")
→ "Found 5 unresolved errors in the EU Sentry..."
```
### Why Internal Integration?
| Auth Type | Tied To | Multi-Org? | Best For |
|-----------|---------|------------|----------|
| Personal Token | User | Yes (user's orgs) | Personal scripts |
| Internal Integration | Organization | No (single org) | Automated systems |
| Public Integration | OAuth | Yes (via OAuth) | Third-party SaaS |
Internal Integration is correct because:
- **Not tied to a person** - survives employee departures
- **Organization-scoped** - clear access boundaries
- **No OAuth complexity** - simple bearer token
- **Fine-grained scopes** - request only what you need
## Development
### Local Setup
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate
# Install dependencies
pip install -e ".[dev]"
# Create local config
mkdir -p /tmp/sentry-mcp
cat > /tmp/sentry-mcp/config.yaml << EOF
instances:
sentryUS:
enabled: true
region: us
orgSlug: your-org
EOF
# Create local secret
mkdir -p /tmp/secrets/sentryUS
echo "sntrys_your_token" > /tmp/secrets/sentryUS/auth_token
# Run server
SENTRY_MCP_CONFIG=/tmp/sentry-mcp/config.yaml \
SENTRY_MCP_SECRETS=/tmp/secrets \
python -m sentry_mcp
```
### Building Docker Image
```bash
docker build -t deeptrace/sentry-mcp:latest .
```
### Running Tests
```bash
pytest
```
## Troubleshooting
### "Unknown Sentry instance" Error
The instance name in your tool call doesn't match any configured instance.
1. Check `list_sentry_instances()` output
2. Verify the instance is enabled in config
3. Ensure the K8s secret exists and has `auth_token` key
### "No auth token configured" Error
The secret for the instance wasn't found or is empty.
1. Verify secret exists: `kubectl get secret <secretName> -n deeptrace`
2. Check secret has `auth_token` key: `kubectl get secret <secretName> -o yaml`
3. Ensure secret is mounted correctly in deployment
### API Rate Limiting
Sentry has rate limits. If you hit them:
1. Reduce `limit` parameter in search queries
2. Add delays between bulk operations
3. Consider caching frequently-accessed data
## License
MIT
