### Install Dependencies and Start Dev Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/cloudflare.md

Installs project dependencies using pnpm and starts the local development server for the Cloudflare Worker.

```bash
# Install dependencies
pnpm install

# Start dev server
pnpm dev

# Access at http://localhost:8787

```

--------------------------------

### Setup Environment Files

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/remote.md

Creates necessary .env files from provided examples. This is a prerequisite for configuring environment variables.

```bash
# Creates .env files from examples
make setup-env
```

--------------------------------

### Setup Environment and Agent Skills

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

Run this command to create necessary .env files and install shared agent skills. It also installs skills from getsentry/skills.

```shell
make setup-env
```

--------------------------------

### Install and Build MCP Client CLI

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Install dependencies and build the client from the package directory.

```bash
pnpm install
pnpm build
```

--------------------------------

### Start Development Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

Starts the local development server. Access the application at http://localhost:5173.

```shell
pnpm dev
```

--------------------------------

### Install and Authenticate GitHub CLI

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/pr-management.md

Install the GitHub CLI using a package manager and authenticate your account. Verify the installation and authentication status.

```bash
# Install GitHub CLI
brew install gh  # macOS
# or follow instructions at https://cli.github.com/

# Authenticate
gh auth login

# Verify installation
gh auth status
```

--------------------------------

### Verify MCP Test Client Installation

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Check if the CLI is installed by running the help command. This is a basic verification step.

```bash
# Check CLI is installed
pnpm mcp-test-client --help
```

--------------------------------

### Clone and Install Dependencies

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Clones the repository and installs project dependencies using pnpm.

```bash
cd sentry-mcp
pnpm install
```

--------------------------------

### Start MCP Server with Access Token (Command Line)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/architecture/overview.md

Starts the MCP server via the command line, providing the access token and host. This is useful for direct process communication.

```bash
# Via command line
pnpm start:stdio --access-token=<token> --host=<host>
```

--------------------------------

### Test Package Locally

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Pack and install the package locally to verify functionality before publishing to the registry.

```bash
cd packages/mcp-server
npm pack
npm install -g ./sentry-mcp-server-1.2.3.tgz
SENTRY_ACCESS_TOKEN=... @sentry/mcp-server
```

--------------------------------

### Example Test Session: List Tools

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Perform a test session to verify the connection and list all available tools using the stdio transport.

```bash
# Test 1: Verify connection and tool count
$ pnpm -w run cli --access-token=YOUR_TOKEN "list all available tools"

● Connected to MCP server (stdio)
  ⎿  Tools available

● Here are the available tools:
  1. execute_sentry_tool
  2. find_organizations
  3. find_projects
  [...]
```

--------------------------------

### Start MCP Inspector

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Run this command from the repository root to start the MCP Inspector. It will open at http://localhost:6274.

```bash
# From repo root
pnpm inspector
```

--------------------------------

### Refactoring Verbose Docs to Concise Examples

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/documentation-style-guide.md

Illustrates transforming lengthy prose into a focused section with essential setup commands and clear prerequisites. Use this pattern to make documentation more scannable and actionable.

```markdown
## Setting Up Your Development Environment

First, make sure you have Node.js installed. You can download it from nodejs.org.
Next, install pnpm globally using npm install -g pnpm. Then clone the repository
using git clone. Navigate to the project directory and run pnpm install to install
all dependencies. Make sure to create your .env file with the required variables.
```

```markdown
## Environment Setup

Required: Node.js 22.13+, pnpm

```bash
pnpm install
cp .env.example .env  # Add your API keys
```

See "Development Setup" in [AGENTS.md](../../AGENTS.md) for environment variables.
```

--------------------------------

### Run Development Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Starts the development server for the MCP client. Use this to run prompts during development.

```bash
pnpm dev "Your prompt here"
```

--------------------------------

### Install Shared Agent Skills

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

Use this command to install shared skills from getsentry/skills into your local environment. Run this if you need to update skills.

```shell
npx @sentry/dotagents install
```

--------------------------------

### Start MCP Server with Access Token (Environment Variable)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/architecture/overview.md

Starts the MCP server using an environment variable for the access token. This is a common method for local development and CI/CD.

```bash
# Via environment variable
SENTRY_ACCESS_TOKEN=<token> pnpm start:stdio
```

--------------------------------

### Find Logs Example

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/specs/search-events.md

Illustrates how to search for logs by specifying the 'logs' dataset. This example filters for warning logs related to memory usage.

```typescript
// Find logs
search_events({
  organizationSlug: "my-org",
  query: "warning logs about memory usage",
  dataset: "logs"
})
```

--------------------------------

### Run Sentry MCP with Direct OpenAI

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/specs/embedded-agent-openai-routing.md

Example command to run the server, which auto-detects the openai provider when an API key is present.

```bash
npx @sentry/mcp-server --access-token=TOKEN
```

--------------------------------

### Example: Feature Addition Commit

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/pr-management.md

Use this format for committing new features, including a clear description and AI attribution if applicable.

```bash
# Feature addition
git commit -m "feat(tools): add natural language search for events

Implement AI-powered query translation using OpenAI GPT-4 to convert
natural language queries into Sentry search syntax. Supports multiple
datasets: errors, logs, and spans.

Co-Authored-By: Codex CLI Agent <noreply@openai.com>"
```

--------------------------------

### Start Local Development Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/remote.md

Starts the Cloudflare Workers local dev environment with hot reload and local KV storage. Serves the web UI at root and MCP endpoint at `/mcp`. Use this for local development.

```bash
# From repo root
pnpm dev

# Or from cloudflare package
cd packages/mcp-cloudflare
pnpm dev
```

--------------------------------

### Run Quality Checks and Publish

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Execute mandatory linting, type checking, testing, and build processes before publishing the package to npm.

```bash
pnpm -w run lint:fix
pnpm tsc --noEmit
pnpm test
pnpm run build

cd packages/mcp-server
npm publish --dry-run
npm publish

git tag v1.2.3
git push origin v1.2.3
```

--------------------------------

### Run Agent CLI Test with Claude and Repo Setup

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/agent-cli-test/README.md

Execute smoke tests for the Claude agent CLI using the repository's local MCP configuration. Ensure the target CLI is installed and authenticated.

```bash
pnpm -w run agent-cli-test --provider claude --setup repo
```

--------------------------------

### Start Interactive Session

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Run the client without arguments to start an interactive session. Type prompts and press Enter. Use 'exit' or 'quit' to end. The AI maintains context across prompts.

```bash
pnpm mcp-test-client
```

--------------------------------

### Example MCP Configuration JSON

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

Example JSON configuration for the Sentry MCP server, specifying command, arguments, and environment variables. This includes settings for LLM providers and self-hosted deployments.

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

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

--------------------------------

### Bad TypeScript Code Example for Parameter Schema

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/documentation-style-guide.md

Demonstrates an overly verbose example that includes general explanations and redundant comments, which should be avoided.

```typescript
// First, import the required libraries
import { z } from "zod";

// Define a schema for the organization slug parameter
// This schema will validate that the input is a string
// It will also convert to lowercase and trim whitespace
export const ParamOrganizationSlug = z
  .string() // Ensures the value is a string
  .toLowerCase() // Converts to lowercase
  .trim() // Removes whitespace
  .describe("The organization's slug..."); // Adds description

```

--------------------------------

### Run Token Cost Measurement (CLI)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/operations/token-cost-tracking.md

Execute the token cost measurement script using the CLI. This example shows how to display the table or write the output to a JSON file.

```bash
tsx measure-token-cost.ts              # Display table
tsx measure-token-cost.ts -o file.json # Write JSON to file
tsx measure-token-cost.ts --help       # Show help
```

--------------------------------

### Run Agent CLI Test with Claude and Stdio Setup

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/agent-cli-test/README.md

Execute smoke tests for the Claude agent CLI using the stdio setup. This requires the stdio package to be built.

```bash
pnpm -w run agent-cli-test --provider claude --setup stdio
```

--------------------------------

### Find Request Duration Metrics Example

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/specs/search-events.md

Demonstrates how to find request duration metrics using the 'metrics' dataset. This example queries for p95 request duration by transaction within the current week.

```typescript
// Find request duration metrics
search_events({
  organizationSlug: "my-org",
  query: "p95 request duration by transaction this week",
  dataset: "metrics"
})
```

--------------------------------

### Run Sentry MCP Development Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/CLAUDE.md

Starts the development server for Sentry MCP. Use this for local development and testing.

```bash
pnpm run dev
```

--------------------------------

### Get Project Settings

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Retrieves the alert settings for a specified project.

```bash
pnpm mcp-test-client "Show me the alert settings for my React project"
```

--------------------------------

### Run MCP Server with pnpm start (Development)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Use this command for active development with TypeScript sources. It runs TypeScript directly without building.

```bash
cd packages/mcp-server
pnpm start --access-token=YOUR_TOKEN
```

--------------------------------

### Run Agent CLI Test with Codex and Stdio Setup

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/agent-cli-test/README.md

Execute smoke tests for the Codex agent CLI using the stdio setup. This requires the stdio package to be built.

```bash
pnpm -w run agent-cli-test --provider codex --setup stdio
```

--------------------------------

### Configure Environment for Evaluations

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

An example of the .env file required in the project root for running evaluations. It includes the OpenAI API key.

```shell
# .env (in project root)
OPENAI_API_KEY=  # Also required for AI-powered search tools in production
```

--------------------------------

### Configure VSCode with MCP Extension

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Integrate the Sentry MCP server into VSCode by installing the MCP extension and configuring `.vscode/settings.json`.

```json
{
  "mcp.servers": {
    "sentry": {
      "command": "npx",
      "args": [
        "@sentry/mcp-server@latest",
        "--access-token=YOUR_TOKEN"
      ]
    }
  }
}
```

--------------------------------

### Test find_projects with Parameters

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/remote.md

Example JSON payload for testing the `find_projects` tool with specific parameters, such as filtering by bookmarks.

```json
// Test find_projects with parameters
{
  "organizationSlug": "your-org",
  "query": "bookmarks:true"
}
```

--------------------------------

### Two-Tier Agent Data Flow Example

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/architecture/overview.md

Demonstrates the data flow in a two-tier agent architecture, from user request to Sentry API call and result presentation.

```text
1. User: "Show me errors from yesterday"
   ↓
2. Claude: Calls search_events(query="errors from yesterday")
   ↓
3. MCP Tool Handler: Receives request
   ↓
4. Embedded Agent (GPT-5):
   - 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
```

--------------------------------

### Create New IDE Instruction Component

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/integrations/ide-instructions-refactor.md

Create a new React component to handle instructions for a new IDE, accepting a 'transport' prop to differentiate between cloud and stdio setups.

```typescript
interface NewIDEInstructionsProps {
  transport: "cloud" | "stdio";
}

export function NewIDEInstructions({ transport }: NewIDEInstructionsProps) {
  if (transport === "cloud") {
    return (
      <ol>
        <li>Cloud setup instructions...</li>
      </ol>
    );
  }

  return (
    <ol>
      <li>Stdio setup instructions...</li>
    </ol>
  );
}
```

--------------------------------

### Example Test Session: Test Specific Tool

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Execute a specific tool, such as 'who am I?', within a test session using the stdio transport.

```bash
# Test 2: Test a specific tool
$ pnpm -w run cli --access-token=YOUR_TOKEN "who am I?"

● Connected to MCP server (stdio)
  ⎿  Tools available

● execute_sentry_tool(name="whoami", arguments={})
  ⎿  You are authenticated as: user@example.com
```

--------------------------------

### Pin Package Version

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Specify a exact version for the MCP server in the client configuration to ensure stability.

```json
{
  "args": ["-y", "@sentry/mcp-server@1.2.3"]
}
```

--------------------------------

### Document Release Changes

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Update the CHANGELOG.md file to reflect new features, fixes, and version information.

```markdown
## [1.2.3] - 2025-01-16

### Added
- New `search_docs` tool for documentation search

### Fixed
- Fix context propagation in tool handlers
```

--------------------------------

### Build Project

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Compiles the project for production.

```bash
pnpm build
```

--------------------------------

### Configure Package Version

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Update the package version in the package.json file following semantic versioning standards.

```json
{
  "name": "@sentry/mcp-server",
  "version": "1.2.3"
}
```

--------------------------------

### Good TypeScript Code Example for Parameter Schema

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/documentation-style-guide.md

Illustrates a concise and effective way to define a tool parameter schema using Zod, focusing only on project-specific patterns.

```typescript
// Tool parameter pattern used throughout the codebase
export const ParamOrganizationSlug = z
  .string()
  .toLowerCase()
  .trim()
  .describe("The organization's slug. Find using `find_organizations()` tool.");

```

--------------------------------

### Configure MCP Client

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Add the Sentry MCP server to the configuration files for Claude Desktop or Cursor IDE.

```json
{
  "mcpServers": {
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": {
        "SENTRY_ACCESS_TOKEN": "sntrys_...",
        "SENTRY_HOST": "sentry.io"
      }
    }
  }
}
```

--------------------------------

### Get Machine-Readable Output from Agent CLI Test

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/agent-cli-test/README.md

Run the Codex agent CLI test with stdio setup and request machine-readable JSON output. This is useful for automated parsing.

```bash
pnpm -w run agent-cli-test --provider codex --setup stdio --json
```

--------------------------------

### Publish Beta Release

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/releases/stdio.md

Publish a beta version to npm for testing purposes and configure the client to use the beta tag.

```bash
npm publish --tag beta
```

```json
{
  "args": ["-y", "@sentry/mcp-server@beta"]
}
```

--------------------------------

### Create Mock API Endpoint

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/adding-tools.md

Define mock handlers for your tool's API endpoint in `packages/mcp-server-mocks/src/handlers/`. This example shows a GET request with basic parameter validation and fixture response.

```typescript
{
  method: "get",
  path: "/api/0/organizations/:org/your-endpoint/",
  fetch: async ({ request, params }) => {
    // Validate parameters
    if (!params.org) {
      return HttpResponse.json("Invalid org", { status: 400 });
    }
    
    // Return fixture
    return HttpResponse.json(yourDataFixture);
  }
}
```

--------------------------------

### List All Projects

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Lists all projects the user has access to, including their platforms.

```bash
pnpm mcp-test-client "List all my projects with their platforms"
```

--------------------------------

### Run Agent CLI Test with Codex and Repo Setup

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/agent-cli-test/README.md

Execute smoke tests for the Codex agent CLI using the repository's local MCP configuration. Ensure the target CLI is installed and authenticated.

```bash
pnpm -w run agent-cli-test --provider codex --setup repo
```

--------------------------------

### Testing Multiple Clients Independently

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/remote.md

This example demonstrates testing multiple clients to ensure they function independently and that per-client constraints are applied. It involves running the CLI client with different user sessions.

```bash
# Terminal 1: Client A
pnpm -w run cli "who am I?"

# Terminal 2: Client B (different user)
rm ~/.sentry-mcp-tokens.json
pnpm -w run cli "who am I?"

# Verify both work independently
# Verify constraints apply per-client
```

--------------------------------

### Run MCP Server with npx (End-user Experience)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Test the published package experience. This includes running the latest version from npm or testing a local build after packing.

```bash
# Latest from npm
npx @sentry/mcp-server@latest --access-token=YOUR_TOKEN
```

```bash
# Test local build (after packing)
cd packages/mcp-server
pnpm pack
npx ./sentry-mcp-server-*.tgz --access-token=YOUR_TOKEN
```

--------------------------------

### Run MCP Client CLI with Access Token and Prompt

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Execute the client with a provided access token and a specific prompt.

```bash
pnpm mcp-test-client --access-token=your_token "Your prompt"
```

--------------------------------

### Import New IDE Instructions in remote-setup.tsx

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/integrations/ide-instructions-refactor.md

Import the NewIDEInstructions component and add it to the RemoteSetupTabs, specifying the 'cloud' transport.

```typescript
import { NewIDEInstructions } from "./instructions/new-ide";

// Add to RemoteSetupTabs:
<Tab id="new-ide" title="New IDE">
  <NewIDEInstructions transport="cloud" />
</Tab>
```

--------------------------------

### Connect to Local MCP Server with Prompt

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Connect to a local MCP server and provide a prompt to execute.

```bash
pnpm mcp-test-client --mcp-host http://localhost:8787 "List my projects"
```

--------------------------------

### Set Up Mock Server for Testing

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/api-patterns.md

Configure the mock server for testing using `@sentry-mcp/mocks`, including listening, resetting handlers, and closing the server.

```typescript
import { setupMockServer } from "@sentry-mcp/mocks";

const server = setupMockServer();

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());
```

--------------------------------

### Import New IDE Instructions in stdio-setup.tsx

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/integrations/ide-instructions-refactor.md

Import the NewIDEInstructions component and add it to the StdioSetupTabs, specifying the 'stdio' transport.

```typescript
import { NewIDEInstructions } from "./instructions/new-ide";

// Add to StdioSetupTabs:
<Tab id="new-ide" title="New IDE">
  <NewIDEInstructions transport="stdio" />
</Tab>
```

--------------------------------

### Good PR Description Example

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/pr-management.md

An example of a concise and reviewer-focused PR description. It effectively summarizes the changes and their impact without unnecessary technical jargon.

```markdown
## Summary
Fixes search_events tool to properly understand OpenTelemetry semantic conventions and refactors the code into a clean module structure.

### Key Changes
- Fixed semantic understanding: "agent calls" now correctly maps to GenAI conventions (`gen_ai.*`) instead of MCP tool calls
- Refactored 1385-line monolithic file into 8 focused modules with clear responsibilities
- Added dynamic semantic lookup for better attribute disambiguation

 

```

--------------------------------

### AI Feedback Validation Examples

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/pr-management.md

Examples of common AI feedback that requires careful validation regarding error handling, performance optimizations, and refactoring.

```bash
# AI suggests error handling - verify it's needed
- "Add error handling for JSON.parse" 
  → Check if error handling exists elsewhere in call chain
```

```bash
# AI suggests performance optimizations - verify impact  
- "Use useMemo for expensive calculations"
  → Measure if optimization is actually needed
```

```bash
# AI suggests refactoring - verify consistency
- "Extract this into a separate function"
  → Check if it follows existing code patterns
```

--------------------------------

### Test CLI Help

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Tests the command-line interface help output for the mcp-server.

```bash
node packages/mcp-server/dist/index.js --help
```

--------------------------------

### Bad PR Description Example

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/pr-management.md

An example of a PR description that is too verbose and includes unnecessary details. It covers technical implementation, test plans, and file structure, which should be omitted.

```markdown
## Summary
This PR implements comprehensive improvements to the search_events tool...

### Technical Implementation Details
- Uses OpenAI GPT-4 for natural language processing
- Implements sophisticated caching mechanisms
- Creates extensive test coverage with MSW mocks
- Follows advanced TypeScript patterns

### Test Plan
1. Run `pnpm test` to verify all tests pass
2. Test with various query types:
   - "agent calls" should return GenAI spans
   - "database errors" should return DB-related errors
3. Verify the UI displays results correctly
4. Check that performance remains optimal

### File Structure Changes
- src/tools/search-events.ts → src/tools/catalog/search-events.ts
- Added src/tools/support/search-events/agent.ts for AI logic
- [... detailed file-by-file breakdown ...]

```

--------------------------------

### OAuth Authorization - GET

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/specs/remembered-oauth-skills.md

Handles the GET request for OAuth authorization. It looks up the client, reads skill preferences from cookies, and passes matching skills to the approval dialog.

```APIDOC
## GET /oauth/authorize

### Description
Handles the GET request for OAuth authorization. It looks up the client, reads skill preferences from cookies, and passes matching skills to the approval dialog.

### Method
GET

### Endpoint
/oauth/authorize
```

--------------------------------

### Initialize MCP Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/architecture/overview.md

Initializes the MCP server using the official SDK. Use this to set up the server name and version.

```typescript
const server = new Server({
  name: "sentry-mcp",
  version: "1.0.0"
});

server.setRequestHandler(ListToolsRequestSchema, () => ({
  tools: TOOL_DEFINITIONS
}));
```

--------------------------------

### Install Claude Code Plugin

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

Install the sentry-mcp plugin for Claude Code to enable automatic subagent delegation for Sentry-related queries. Use the experimental version for forward-looking features.

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

```shell
claude plugin install sentry-mcp@sentry-mcp-experimental
```

--------------------------------

### Perform Quick Smoke Test

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Starts the MCP server and performs a basic 'tools/list' RPC call to verify server responsiveness. Useful for quick checks without running the full test suite.

```bash
cd packages/mcp-server
pnpm start --access-token=TOKEN & 
sleep 2
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | pnpm start --access-token=TOKEN
```

--------------------------------

### Find Slow Transactions Example

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/specs/search-events.md

Shows how to search for slow transactions by specifying the 'spans' dataset and a project slug. This example targets API calls exceeding 5 seconds.

```typescript
// Find slow transactions
search_events({
  organizationSlug: "my-org",
  query: "API calls taking over 5 seconds",
  projectSlug: "backend",
  dataset: "spans"
})
```

--------------------------------

### List Available Tools

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/remote.md

Use the CLI to list available tools and their names. This helps in diagnosing 'Tool not found' errors.

```bash
# Check tool list
pnpm -w run cli "list tools" | jq '.tools[] | .name'
```

--------------------------------

### Sentry API Absolute Time Filtering

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/search-events-api-patterns.md

Filter events using absolute start and end times in ISO 8601 format. Both `start` and `end` parameters must be provided together.

```http
?start=2025-06-19T07:00:00&end=2025-06-20T06:59:59
```

--------------------------------

### Run MCP Inspector

Source: https://github.com/getsentry/sentry-mcp/blob/main/README.md

Launch the MCP Inspector tool to test the service. Connect using the provided MCP server URL. Use 'localhost' if experiencing OAuth issues with '127.0.0.1'.

```shell
pnpm inspector
```

--------------------------------

### Configure MCP Client via Environment Variables

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Set up environment variables in a .env file for API keys, Sentry tokens, hostnames, and models.

```env
OPENAI_API_KEY=your_openai_api_key
SENTRY_ACCESS_TOKEN=your_sentry_access_token
SENTRY_HOST=sentry.example.com
MCP_URL=https://mcp.sentry.dev
MCP_MODEL=gpt-4o
SENTRY_DSN=your_sentry_dsn
```

--------------------------------

### Run MCP Client CLI with OAuth

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Execute the client, which will prompt for OAuth if no token is provided. Optionally specify a custom MCP host.

```bash
pnpm mcp-test-client
pnpm mcp-test-client --mcp-host http://localhost:8787
```

--------------------------------

### Run MCP Server with Built Package (Production-like)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Test the actual build output of the MCP server. This can be run from the repository root or using a workspace command.

```bash
# From repo root
node packages/mcp-server/dist/index.js --access-token=YOUR_TOKEN
```

```bash
# Or use the workspace command
pnpm -w run mcp-server --access-token=YOUR_TOKEN
```

--------------------------------

### IDE Instruction Component Pattern

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/integrations/ide-instructions-refactor.md

This pattern defines the structure for IDE instruction components, separating cloud/remote setup from stdio setup within a single file. It ensures a single source of truth for each IDE's instructions.

```typescript
interface InstructionProps {
  transport: 'cloud' | 'stdio';
}

export function ClaudeCodeInstructions({ transport }: InstructionProps) {
  if (transport === 'cloud') {
    // Cloud/remote setup instructions with OAuth
    return <CloudInstructions />;
  }

  // Stdio setup instructions with CLI command
  return <StdioInstructions />;
}
```

--------------------------------

### Build All Packages

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Builds all packages within the monorepo, including the mcp-server.

```bash
pnpm -w run build
```

--------------------------------

### Get Issue Details

Source: https://github.com/getsentry/sentry-mcp/blob/main/packages/mcp-test-client/README.md

Retrieves detailed information about a specific issue.

```bash
pnpm mcp-test-client "Show me details about issue FRONTEND-123"
```

--------------------------------

### Test with Development Server

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Runs the MCP server in development mode, connecting to a self-hosted Sentry instance. Requires a valid access token and the Sentry host URL.

```bash
pnpm start \
  --access-token=TOKEN \
  --host=sentry.local.dev
```

--------------------------------

### Legacy Discover Response Format

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/search-events-api-patterns.md

Example of the JSON response structure for the errors dataset in legacy Discover.

```json
{
  "data": [
    {
      "error.type": "TypeError",
      "count()": 150,
      "last_seen()": "2025-01-16T12:00:00Z"
    }
  ]
}
```

--------------------------------

### Example: Refactoring Commit

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/pr-management.md

Use the 'refactor' type for code changes that improve structure without altering functionality.

```bash
# Refactoring
git commit -m "refactor: move tool test to appropriate directory

Move toolDefinitions.test.ts to tools/ directory and rename to tools.test.ts
to fix circular dependency and improve organization.

Co-Authored-By: Codex CLI Agent <noreply@openai.com>"
```

--------------------------------

### Run Full Rebuild and Test Cycle

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/stdio.md

Execute a complete build process followed by all tests. This is useful for ensuring the entire project is functional after significant changes.

```bash
pnpm -w run build && pnpm -w run test
```

--------------------------------

### EAP Response Format (Spans/Logs)

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/contributing/search-events-api-patterns.md

Example of the JSON response structure for spans and logs datasets in the EAP (Explore API).

```json
{
  "data": [
    {
      "span.op": "db.query",
      "count()": 1250,
      "avg(span.duration)": 45.3
    }
  ]
}
```

--------------------------------

### Verify Resource Constraints

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/testing/remote.md

Check the URL for resource constraints and verify your access to the specified organization and project using the CLI.

```bash
# Verify constraint in URL
echo "Accessing: http://localhost:5173/mcp-org-slug/project-slug"
```

```bash
# Verify you have access to that org/project
pnpm -w run cli --mcp-host=http://localhost:5173/mcp \
  "find_organizations()"
```

--------------------------------

### Cloudflare Wrangler Configuration Variables

Source: https://github.com/getsentry/sentry-mcp/blob/main/docs/cloudflare/architecture.md

Example TOML configuration for Cloudflare Workers, specifying required environment variables for deployment.

```toml
[vars]
COOKIE_SECRET = "..."      # For session encryption
OPENAI_API_KEY = "..."     # For GPT-4 access
SENTRY_CLIENT_ID = "..."   # OAuth app ID
SENTRY_CLIENT_SECRET = "..." # OAuth app secret
```