Skip to main content

Sentry

Sentry is an error monitoring and application performance monitoring platform that helps developers track, diagnose, and fix bugs in production applications. It provides real-time error tracking, performance monitoring, release health tracking, and powerful debugging tools to improve application reliability.

Authentication Types​

Sentry supports 2 authentication methods:

  • API Key (Auth Tokens) - Uses bearer token authentication from internal integrations

    • Pros: Simple setup, good for automation, no user interaction required
    • Cons: Requires manual token creation in Sentry, tokens tied to integration permissions
    • Best for: Server-side automation, CI/CD pipelines, scripts

  • OAuth 2.0 - User-delegated access with granular scope-based permissions

    • Pros: Secure user authentication, granular permissions, automatic token refresh
    • Cons: More complex initial setup, requires OAuth app creation
    • Best for: User-facing applications, multi-user environments

General Settings​

Before using the connector, you need to configure:

  • Sentry Region - Your Sentry instance region determines the API endpoint. Options:
    • sentry.io (SaaS - multi-region, recommended for most users)
    • us.sentry.io (US region)
    • de.sentry.io (Germany/EU region)
tip

If you're using Sentry SaaS (not self-hosted), you can typically use sentry.io. Check your Sentry URL in the browser - if you access Sentry at https://sentry.io/..., use sentry.io as your region.

Setting up API Key (Auth Tokens)​

API Keys (Auth Tokens) provide programmatic access to your Sentry organization through internal integrations.

Creating an Internal Integration​

  1. Log in to your Sentry account and select your organization

  2. Navigate to Settings → Developer Settings → Internal Integrations

  3. Click Create New Integration

  4. Fill in the integration details:

    • Name: "Webrix MCP Integration" (or your preferred name)
    • Webhook URL: Leave empty (not needed for API access)
    • Redirect URL: Leave empty

  5. Configure Permissions by selecting the appropriate scopes:

    • Organization: Read, Write, Admin (choose based on your needs)
    • Project: Read, Write, Admin
    • Team: Read, Write, Admin
    • Member: Read, Write, Admin
    • Event: Read, Write, Admin
    • Release: Admin (includes read/write for releases)

    Recommended minimum scopes for basic usage:

    • Organization: Read
    • Project: Read
    • Event: Read, Write
    • Release: Admin

  6. Click Save Changes

  7. Copy the Token that appears (you won't be able to see it again)

Configuring in Webrix​

  1. In the Webrix connector settings, select API Key as the authentication method

  2. Enter your Sentry Region (e.g., sentry.io)

  3. Paste your Auth Token in the token field

  4. Click Save Changes

warning

Keep your auth token secure. It provides access to your Sentry organization based on the permissions you configured. Never commit tokens to source control or share them publicly.

Setting up OAuth​

OAuth provides secure, user-delegated access with automatic token management and granular permissions.

Creating an OAuth Application​

  1. Log in to your Sentry account with admin privileges

  2. Navigate to Settings → Developer Settings → OAuth Applications

  3. Click Create New Application

  4. Fill in the application details:

    • Application Name: "Webrix MCP Integration"
    • Homepage URL: https://webrix.ai (or your application URL)
    • Privacy Policy URL: (optional)
    • Terms of Service URL: (optional)
    • Webhook URL: Leave empty

  5. Redirect URIs: Add the callback URL provided by Webrix

    • This will be shown in the Webrix connector configuration page
    • Example: https://app.webrix.ai/auth/callback

  6. Scopes: Select the permissions your integration needs:

    • org:read - List and read organizations
    • org:write - Update organizations
    • org:admin - Full organization access
    • project:read - List and read projects
    • project:write - Create and update projects
    • project:admin - Delete projects
    • team:read - List and read teams
    • team:write - Create and update teams
    • team:admin - Delete teams
    • member:read - List organization members
    • member:write - Manage members
    • event:read - Read issues and events
    • event:write - Update and resolve issues
    • event:admin - Delete issues
    • project:releases - Manage releases (includes read/write)

    Recommended scopes for full functionality:

    • org:read, project:read, project:write, team:read, event:read, event:write, project:releases

  7. Click Save

  8. Copy the Client ID (visible on the page)

  9. Copy the Client Secret (shown only once - store it securely)

Configuring in Webrix​

  1. In the Webrix connector settings, select OAuth as the authentication method

  2. Enter your Sentry Region (e.g., sentry.io)

  3. Enter the Client ID from your OAuth application

  4. Enter the Client Secret from your OAuth application

  5. Click Save Changes

  6. Click Connect to initiate the OAuth flow

  7. Log in with your Sentry credentials and authorize the application

  8. You'll be redirected back to Webrix with a successful connection

tip

OAuth uses PKCE (Proof Key for Code Exchange) for enhanced security. This is enabled automatically and requires no additional configuration. Access tokens expire after 30 days but are automatically refreshed.

Available Tools​

The Sentry connector provides 25 tools organized into categories:

Organizations (3 tools)​

  • List Organizations - Discover all organizations you have access to
  • Get Organization - Retrieve detailed organization information and settings
  • List Organization Projects - List all projects within an organization

Projects (5 tools)​

  • Get Project - Retrieve detailed project information
  • Create Project - Create a new project in a team
  • Update Project - Modify project settings
  • Delete Project - Remove a project permanently
  • List Project Issues - List issues for a specific project with filtering

Teams (4 tools)​

  • List Teams - Discover teams in an organization
  • Get Team - Retrieve team details and configuration
  • Create Team - Create a new team
  • List Team Projects - See which projects a team manages

Issues & Events (7 tools)​

  • List Issues - Search and filter issues across projects with advanced queries
  • Get Issue - Retrieve detailed issue information and metadata
  • Update Issue - Change issue status, assignee, or properties
  • Resolve Issue - Mark issues as resolved
  • Delete Issue - Permanently remove issues
  • Bulk Mutate Issues - Update up to 1000 issues at once
  • List Issue Events - See all occurrences of a specific issue

Releases (4 tools)​

  • List Releases - Browse application releases and versions
  • Create Release - Create a new release version
  • Get Release - Retrieve release details and health statistics
  • Delete Release - Remove a release

Monitors (2 tools)​

  • List Monitors - View cron job monitors
  • Get Monitor - Retrieve monitor configuration and check-in history

Common Use Cases​

Investigating Production Errors​

"Show me all unresolved errors in my production project from the last 24 hours"

"Get details for issue SENTRY-123"

"List all critical level errors assigned to me"

Managing Issues​

"Resolve issue 456789"

"Assign all unresolved TypeError issues to user:123"

"Bulk update all issues in release 2.5.0 to resolved"

Release Management​

"Create a new release for version 3.0.0"

"List all releases for my-project in the last month"

"Get health statistics for release 2.5.0"

Team & Project Organization​

"List all teams in my organization"

"Show me all projects assigned to the backend team"

"Create a new project called 'mobile-app' in the mobile team"

Advanced Searching​

"Find all issues with the query: 'is:unresolved level:error browser:chrome environment:production'"

"List issues that have the tag 'payment-flow' and occurred in the last 7 days"

Monitoring Scheduled Jobs​

"List all cron monitors in my organization"

"Check the status of monitor 'daily-backup-job'"

Troubleshooting​

"Authentication Failed" Error​

Cause: Invalid auth token, expired OAuth credentials, or incorrect region.

Solution:

For API Keys:

  • Verify your auth token is correct and hasn't been revoked
  • Check that you copied the full token without extra spaces
  • Ensure the internal integration has the necessary permissions
  • Regenerate the token if needed in Sentry's Developer Settings

For OAuth:

  • Verify your Client ID and Client Secret are correct
  • Check that the redirect URI matches exactly (including https://)
  • Ensure your OAuth app has the required scopes
  • Try disconnecting and reconnecting to refresh tokens
  • Check if your OAuth app is still active in Sentry

"Invalid Region" or API Endpoint Errors​

Cause: The Sentry region is not configured correctly.

Solution:

  • Check the URL you use to access Sentry in your browser
  • If you access https://sentry.io/..., use sentry.io as your region
  • If you access https://us.sentry.io/..., use us.sentry.io
  • If you access https://de.sentry.io/..., use de.sentry.io
  • For self-hosted Sentry, use your custom domain
  • Don't include https:// or trailing slashes in the region

"Permission Denied" or "Forbidden" Errors​

Cause: The auth token or OAuth scopes lack required permissions.

Solution:

For API Keys:

  • Check the permissions configured for your internal integration
  • Ensure the integration has the necessary scopes for the operation
  • Common required scopes:
    • Listing/reading: org:read, project:read, event:read
    • Creating/updating: project:write, event:write
    • Deleting: project:admin, event:admin
    • Releases: project:releases

For OAuth:

  • Review the scopes granted to your OAuth application
  • Add missing scopes in the OAuth app configuration in Sentry
  • Disconnect and reconnect to grant new permissions

"Organization Not Found" Error​

Cause: Organization slug is incorrect or you don't have access.

Solution:

  • Use the "List Organizations" tool to see organizations you can access
  • Verify the organization slug is correct (lowercase, with hyphens)
  • Check that your auth has access to the organization
  • Organization slugs are found in Sentry URLs: https://sentry.io/organizations/YOUR-ORG-SLUG/

"Project Not Found" Error​

Cause: Project slug is incorrect or doesn't exist.

Solution:

  • Use "List Organization Projects" to see available projects
  • Verify the project slug is correct
  • Ensure the project belongs to the specified organization
  • Project slugs are found in Sentry URLs: https://sentry.io/organizations/org/projects/PROJECT-SLUG/

Rate Limit Errors​

Cause: Too many API requests in a short time period.

Solution:

  • Sentry has rate limits that vary by plan (typically 3000-5000 requests per hour)
  • Wait a few minutes before retrying
  • Use pagination and filtering to reduce request count
  • Avoid making redundant requests
  • Consider caching frequently accessed data
  • Check your rate limit status in API response headers

Issue Query Syntax Errors​

Cause: Invalid search query syntax.

Solution:

Common query patterns:

  • Status: is:unresolved, is:resolved, is:ignored
  • Level: level:error, level:warning, level:fatal
  • Time: age:-24h, firstSeen:-7d, lastSeen:+1h
  • Assignment: assigned:me, assigned:[email protected], unassigned:true
  • Environment: environment:production, environment:[production, staging]
  • Release: release:1.0.0, !release:1.0.0
  • Tags: browser:chrome, os:android
  • Combining: Use spaces for AND (e.g., is:unresolved level:error browser:chrome)

Refer to Sentry's search syntax documentation for advanced queries.

No Data Returned from Queries​

Cause: Query filters might be too restrictive or data doesn't exist.

Solution:

  • Start with a broad query and narrow down with filters
  • Verify the time period includes data (use statsPeriod parameter)
  • Check that issues exist in the project using the Sentry web UI
  • Remove filters one by one to identify which is too restrictive
  • Ensure project IDs or slugs are correct

Best Practices​

Security​

  • Use OAuth for user-facing integrations to leverage per-user permissions
  • Use API Keys for server-side automation and CI/CD pipelines
  • Rotate auth tokens regularly for security
  • Never commit credentials to source control
  • Use minimum required scopes for integrations
  • Revoke unused integrations and OAuth apps

Issue Management​

  • Use search queries to filter issues efficiently
  • Leverage bulk operations for managing multiple issues
  • Assign issues to appropriate team members
  • Use status updates to track issue workflow
  • Bookmark critical issues for quick access
  • Subscribe to important issues for notifications

Release Tracking​

  • Create releases for every deployment
  • Associate releases with specific projects
  • Include commit information in releases
  • Track release health and adoption
  • Use releases to filter issues by version
  • Delete old releases to keep data clean

Organization​

  • Use consistent naming conventions for projects and teams
  • Organize projects by team for better access control
  • Set up appropriate permissions for team members
  • Use descriptive team and project names
  • Keep organization structure aligned with your actual teams

Performance​

  • Use specific filters to reduce data returned
  • Paginate through large result sets using cursors
  • Cache frequently accessed data (organization/project lists)
  • Use appropriate time ranges for queries
  • Avoid querying all projects when you only need one
  • Use bulk operations instead of individual updates when possible

Monitoring​

  • Set up monitors for critical scheduled jobs
  • Review monitor check-in history regularly
  • Use descriptive monitor names
  • Configure appropriate alert thresholds
  • Test monitors after creation
  • Keep monitor schedules up to date