Sentry MCP

--- description: globs: alwaysApply: false --- # Architecture System design and package interactions for the Sentry MCP server. ## Overview Sentry MCP is a Model Context Protocol server that exposes Sentry's functionality to AI assistants. It provides tools, prompts, and resources that enable LLMs to interact with Sentry's error tracking, performance monitoring, and other features. ## Package Structure The project is a pnpm monorepo with clear separation of concerns: ``` packages/ ├── mcp-server/ # Core MCP server (npm package) ├── mcp-cloudflare/ # Cloudflare Workers deployment ├── mcp-server-evals/ # Evaluation test suite ├── mcp-server-mocks/ # Shared mock data └── mcp-test-client/ # Interactive CLI client ``` ### packages/mcp-server The core MCP implementation and npm-publishable package. **Structure:** ``` src/ ├── api-client/ # Sentry API client ├── internal/ # Utilities (not exposed) ├── transports/ # Transport implementations ├── tools.ts # Tool handler implementations ├── toolDefinitions.ts # Tool schemas and metadata ├── prompts.ts # Prompt implementations ├── resources.ts # Resource handlers ├── errors.ts # Custom error types └── types.ts # TypeScript definitions ``` **Key responsibilities:** - Implements MCP protocol using the official SDK - Provides tools for Sentry operations (issues, projects, etc.) - Handles authentication and API communication - Formats responses for LLM consumption ### packages/mcp-cloudflare A separate web chat application that uses the MCP server. **Note**: This is NOT part of the MCP server itself - it's a demonstration of how to build a chat interface that consumes MCP. See "Overview" in @docs/cloudflare/overview.md for details. ### packages/mcp-server-evals Evaluation tests that verify real Sentry operations. **Uses:** - Vercel AI SDK for LLM integration - Real Sentry API calls with mocked responses - Factuality scoring for output validation ### packages/mcp-server-mocks Centralized mock data and MSW handlers. **Provides:** - Fixture data for all Sentry entities - MSW request handlers - Shared test utilities ### packages/mcp-test-client Interactive CLI for testing the MCP server with an AI agent. **Key features:** - Vercel AI SDK integration with Anthropic - Interactive and single-prompt modes - OAuth authentication for remote servers - Stdio transport for local testing - Clean terminal output with tool call visualization ## Key Architectural Decisions ### 1. Protocol Implementation Uses the official MCP SDK (`@modelcontextprotocol/sdk`) to ensure compatibility: ```typescript const server = new Server({ name: "sentry-mcp", version: "1.0.0" }); server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: TOOL_DEFINITIONS })); ``` ### 2. Transport Layers The MCP server supports multiple transport mechanisms: **Stdio Transport** (Primary): - Direct process communication - Used by IDEs (Cursor, VS Code) and local tools - Configured via command-line args - This is the standard MCP transport **HTTP/SSE Transport** (For web apps): - Allows web applications to connect to MCP - Used by the example Cloudflare chat app - Not part of core MCP spec ### 3. Authentication Strategy The MCP server uses Sentry access tokens for authentication: ```bash # Via command line pnpm start:stdio --access-token=<token> --host=<host> # Via environment variable SENTRY_ACCESS_TOKEN=<token> pnpm start:stdio ``` For web applications using MCP (like the Cloudflare example), they handle their own authentication and pass tokens to the MCP server. ### 4. API Client Design Centralized client with method-specific implementations: ```typescript class SentryApiService { constructor(private config: { host: string; accessToken: string }) // Resource-specific methods issues = { list: (params) => this.fetch("/issues/", params), get: (params) => this.fetch(`/issues/${id}/`) } } ``` ### 5. Tool Design Pattern Each tool follows a consistent structure: 1. **Definition** (toolDefinitions.ts): - Schema with Zod - LLM-friendly description - Parameter documentation 2. **Handler** (tools.ts): - Parameter validation - API calls via client - Response formatting - Error handling 3. **Testing**: - Unit tests with snapshots - Mock API responses - Evaluation tests **Tool Count Constraints:** - AI agents have a 45 tool limit (Cursor, etc.) - Sentry MCP must stay under 25 tools (target: ~20) - Consolidate functionality where possible - Consider parameter variants over new tools ### 6. Error Handling Philosophy Two-tier error system: - **UserInputError**: Invalid parameters, clear user feedback - **System errors**: Logged to Sentry, generic message to user ### 7. Build System Turbo for monorepo orchestration: - Dependency-aware builds - Parallel task execution - Shared TypeScript configs - Centralized linting/formatting ## Data Flow ``` 1. LLM makes tool call ↓ 2. MCP server receives request ↓ 3. Handler validates parameters ↓ 4. API client makes Sentry call ↓ 5. Response formatted for LLM ↓ 6. MCP sends response back ``` ## MCP Concept Mappings ### Tools Execute actions and retrieve data: - `find_issues` - Search for issues - `get_project_details` - Fetch project info - `create_issue_comment` - Add comments - `search_docs` - Search Sentry documentation - `get_doc` - Fetch full documentation pages ### Prompts Multi-step workflows: - `find_errors_in_file` - Search for errors in a specific file - `fix_issue_with_seer` - AI-suggested fixes ### Resources External documentation and data: - Platform docs (React, Python, etc.) - API references - Configuration examples ## Performance Considerations - Stateless server design - No caching between requests - Streaming responses where applicable - Parallel API calls when possible ## Two-Tier Agent Architecture Some tools (`search_events` and `search_issues`) implement a two-tier agent pattern: ### Tier 1: Calling Agent (Claude/Cursor) - Decides when to use search tools - Provides natural language queries - Handles errors and retries - Interprets results for the user ### Tier 2: Embedded Agent (GPT-4o) - Lives inside the MCP tool - Translates natural language to Sentry query syntax - Has its own tools for field discovery - Returns structured query objects ### Data Flow Example ``` 1. User: "Show me errors from yesterday" ↓ 2. Claude: Calls search_events(naturalLanguageQuery="errors from yesterday") ↓ 3. MCP Tool Handler: Receives request ↓ 4. Embedded Agent (GPT-4o): - Determines dataset: "errors" - Calls datasetAttributes tool - Translates to: {query: "", fields: [...], timeRange: {statsPeriod: "24h"}} ↓ 5. MCP Tool: Executes Sentry API call ↓ 6. Results formatted and returned to Claude ↓ 7. Claude: Presents results to user ``` ### Design Rationale This pattern is used when: - Query languages are complex (Sentry's search syntax) - Available fields vary by context (project-specific attributes) - Semantic understanding is required ("yesterday" → timeRange) ### Error Handling - Embedded agent errors are returned as UserInputError - Calling agent sees the error and can retry - No internal retry loops - single responsibility ## Security Model - Access tokens never logged - OAuth tokens encrypted in KV - Per-organization isolation - CORS configured for security ## Testing Architecture Three levels of testing: 1. **Unit tests**: Fast, isolated, snapshot-based 2. **Integration tests**: With mocked API 3. **Evaluation tests**: Real-world scenarios with LLM ## References - MCP SDK: `@modelcontextprotocol/sdk` - Build config: `turbo.json` - TypeScript config: `packages/mcp-server-tsconfig/` - API client: `packages/mcp-server/src/api-client/`