Step-by-step guide for adding new tools to the Sentry MCP server.
Not every tool is exposed to every consumer. We rely on several mechanisms to keep the active tool set manageable:
- Every tool is direct by default —
EXPOSE_ALL_TOOLSinpackages/mcp-core/src/tools/exposure.tsis on, so every catalog tool that passes the filters below is listed in MCPtools/list, andsearch_sentry_tools+execute_sentry_toolare not registered. Tier 1 harnesses defer MCP tool schemas behind their own tool search, which indexes each tool's name and description, so write both with search in mind. The flag is a code constant, not a runtime option; turning it off restores the gateway surface described in the next bullets. - Deprecated tools — Mark an old name kept for backward compatibility with
deprecated: { replacedBy: ["new_tool"] }on its tool config. Deprecated tools are never listed intools/list, so harness search does not return them next to the tools that replaced them. WithEXPOSE_ALL_TOOLSoff they stay reachable throughexecute_sentry_tool.toolDefinitions.jsoncarries the same field. - Catalog gateway (flag off) — Tools are searchable/executable through
search_sentry_tools+execute_sentry_tool. Search uses the tool's existing name and description. - Catalog registry —
packages/mcp-core/src/tools/catalog/index.tslists ordinary Sentry operation tools. The catalog directory is intentionally flat: one tool entry per file. - Central direct exposure policy (flag off) —
packages/mcp-core/src/tools/surfaces.tslists the catalog tools that are also exposed directly through MCPtools/list. The direct surface intentionally keeps long-tail tools catalog-only becausesearch_sentry_tools+execute_sentry_toolare available as primary primitives. requiredCapabilities— Tools declare which project capabilities they need (e.g.profiles,replays,traces). If the upstream project doesn't have a capability enabled, the tool is automatically hidden.experimental/hideInExperimentalMode— Feature flags for tools that are being tested or replaced.- Skills & constraints — The server filters tools based on granted skills and org/project constraints.
We also expect upstream consumers (Claude Code plugins, Cursor, etc.) to use tool selection or progressive disclosure on their end. The catalog can contain more tools than the direct MCP surface, but the registered top-level tool count must still stay within the limits below.
With EXPOSE_ALL_TOOLS on, harness tool search keeps the full tool list out of the context window, so the limit below applies to the gateway surface (TOP_LEVEL_TOOL_NAMES) that the flag falls back to.
Target ~20 tools on the gateway surface. Never exceed 25. AI agents have limited tool slots (Cursor caps at 45 total across all providers), so Sentry MCP cannot consume all available slots.
Before adding a new tool, consider if it could be:
- Combined with an existing tool
- Implemented as a parameter variant
- Added to the searchable catalog instead of the top-level MCP surface
- Gated behind
requiredCapabilitiesif only relevant to some projects
When a new or changed tool calls a Sentry API endpoint, verify the endpoint
contract against the Sentry source tree in ~/src/sentry before implementing
the MCP schema. Check the endpoint, serializer, URL registration, and tests so
request params, response fields, pagination, feature gates, and retention
behavior match the server. See API Patterns.
After creating a tool module, add it to packages/mcp-core/src/tools/catalog/index.ts. Then update packages/mcp-core/src/tools/surfaces.ts only when it should be directly exposed through MCP tools/list:
- Add only high-frequency, foundational tools to
TOP_LEVEL_TOOL_NAMES. - Leave long-tail tools out of the direct surface unless there is a clear reason they need to be visible without discovery. Tools omitted from this list remain available through
search_sentry_toolsandexecute_sentry_toolafter the normal skill, constraint, experimental, and capability filters pass. - Keep
EXPERIMENTAL_TOP_LEVEL_TOOL_NAMESaligned withTOP_LEVEL_TOOL_NAMESunless a future experimental mode intentionally needs a different direct surface. - Keep private implementation helpers as plain modules/functions instead of MCP tools.
Do not add search-only summaries or catalog-only schemas. search_sentry_tools indexes the existing tool name and description.
Each tool consists of:
- Tool Module - Single file in
src/tools/catalog/your-tool-name.tswith definition and handler - Tests - Unit tests in
src/tools/catalog/your-tool-name.test.ts, including a baseline happy-path inline snapshot - Mocks - API responses in
mcp-server-mocks - Evals - Integration tests (use sparingly)
If a tool needs substantial helper code, put that code under
packages/mcp-core/src/tools/support/ and import it from the flat catalog tool
file. Do not create per-tool subdirectories under tools/catalog/.
Create packages/mcp-core/src/tools/catalog/your-tool-name.ts:
import { z } from "zod";
import { defineTool } from "../../internal/tool-helpers/define";
import { apiServiceFromContext } from "../../internal/tool-helpers/api";
import { ParamOrganizationSlug, ParamRegionUrl } from "../../schema";
import type { ServerContext } from "../../types";
export default defineTool({
name: "your_tool_name",
title: "Your Tool Name",
description:
"List or search widgets in an organization. Returns each widget's name, owner, and URL.",
inputSchema: {
organizationSlug: ParamOrganizationSlug,
regionUrl: ParamRegionUrl.nullable().default(null),
yourParam: z.string().describe("Widget name or ID."),
},
annotations: {
readOnlyHint: true,
destructiveHint: false,
openWorldHint: true,
},
async handler(params, context: ServerContext) {
// Implementation here
},
});REQUIRED: Every tool sets title, a short Title Case display name such as
"Search Issues". The server exports it as the MCP tool title, which clients
show instead of the snake_case name. Titles must be unique across tools; the
metadata linter enforces this for listed
tools, and tools.test.ts for tools that never appear in tools/list. Deprecated
aliases add a (Deprecated) suffix, for example
"Search AI Conversations (Deprecated)".
REQUIRED: Every tool must declare readOnlyHint, destructiveHint, and
openWorldHint explicitly (each true or false, never omitted). This is
enforced at compile time (the annotations type requires them) and by the
metadata linter, because filters and confirmation gates depend on these hints;
an absent hint is a silent gap. Read-only tools must set destructiveHint: false
(not leave it undefined).
Available annotations:
readOnlyHint(boolean): Tool doesn't modify datadestructiveHint(boolean): Tool may modify/delete existing dataidempotentHint(boolean, optional): Repeated calls with same arguments have no additional effectopenWorldHint(boolean): Tool interacts with external services (default: true for API calls)
Annotation patterns:
// Read-only tools (queries, lists, searches)
annotations: {
readOnlyHint: true,
destructiveHint: false,
openWorldHint: true,
}
// Create tools (additive, non-destructive)
annotations: {
readOnlyHint: false,
destructiveHint: false,
openWorldHint: true,
}
// Update tools (modify existing data)
annotations: {
readOnlyHint: false,
destructiveHint: true,
idempotentHint: true, // Same update twice = same result
openWorldHint: true,
}The catalog gives every tool with readOnlyHint: true and
openWorldHint: true a shared fresh input (ParamFresh), except the docs
tools, which do not call the Sentry API. Do not declare fresh yourself. A
call with fresh: true runs the handler in a request scope where the shared
transport skips cached reads, and the handler never sees the input.
Every tool description and param description ships in tools/list for every
session. Spend those tokens only on text that changes what the model does.
Tool descriptions
- Say what the tool does to which Sentry object, and what it returns. Write it in the words a user would type ("stack trace", "client key", "cron monitor"). Harness tool search ranks tools by name and description (Codex uses BM25 and returns 8 matches; see docs/mcp/harnesses.md), and some harnesses cut descriptions to about 120 characters, so the first sentence carries the search terms.
- Name a sibling tool only when the contrast is the contract: two tools that
look alike, such as cron, uptime, and metric monitors, or issues versus
events. One short line, not a
DO NOT USElist. - Do not name input fields. Field meaning lives in
describe()on the param. - No
<examples>,<hints>, "Use this tool when you need to:" lists, or call samples. The schema already shows the call shape. Keep an example only when it teaches a format the model cannot get from the schema, such as Sentry search syntax, and put it on the param. - Not every harness loads the server instructions
(
server-instructions.ts), so tool and param text must work without them. Keep the routing a tool needs, such as "start here for a Sentry URL", in its own description as one short line. The server instructions may repeat it for the harnesses that load them. - Do not narrate how the tool works inside, which API it calls, or that its output is markdown.
- At most
MAX_TOOL_DESCRIPTION_LENGTH(512) characters.
Param descriptions
- Say what the value is, and its format or constraint. Do not repeat the type, the default, the min and max, or a bare list of enum values: JSON Schema already shows them. Explain an enum value only when its name does not.
- Put a rule that ties fields together ("requires
status: resolved", "only withignoreMode: forDuration") on the field that depends on the other. Enforce it in the handler too. - Reuse the shared params in
schema.tsfor the same kind of value (ParamOrganizationSlug,ParamRegionUrl,ParamProjectSlug, and so on). Add.optional(),.nullable(), or.default()at the use site. - At most
MAX_PARAM_DESCRIPTION_LENGTH(256) characters.
Steering lives in one place
- Prefer a schema, an enum, fixed validation, or a repairable
UserInputErrorover a prose rule. When the handler enforces a rule, cut the prose that repeats it. - Give each rule one home: the param for field meaning, the tool description for what the tool does and its sibling contrast, and response notes for follow-ups that depend on the result. The server instructions are the one allowed second copy, because some harnesses never load them.
tool-descriptions.test.ts enforces the limits, rejects <examples> and
<hints>, and fails when a tool description names one of its input fields.
Add the handler implementation to your tool module:
async handler(params, context: ServerContext) {
// 1. Get API service
const api = apiServiceFromContext(context, {
regionUrl: params.regionUrl,
});
// 2. Validate inputs (see common-patterns.md#error-handling)
if (!params.organizationSlug) {
throw new UserInputError(
"Organization slug is required. Use find_organizations() to list."
);
}
// 3. Set telemetry context for streamed spans and error events
// Import from ../../telem/scope.
setTargetTagsAndAttributes(params);
// 4. Call API
const data = await api.yourMethod(params);
// 5. Format response
let output = `# Results in **${params.organizationSlug}**\n\n`;
if (data.length === 0) {
return output + "No results found.\n";
}
// 6. Format data
output += formatYourData(data);
// 7. Add response notes
output += "\n\n## Response Notes\n\n";
output += "- Please tell the user the resource ID.\n";
return output;
}Tool responses must follow tool-responses.md. In particular:
- Format output as user-facing markdown, not raw upstream API payloads.
- Include actionable IDs and URLs when they support navigation or follow-up tool calls.
- Omit internal implementation details, empty placeholder values, and raw JSON unless the tool explicitly exists to return raw data.
- Keep response notes scoped to this result.
See common-patterns.md for shared formatting patterns and examples.
Follow comprehensive testing patterns from ../testing/overview.md for unit, integration, and evaluation tests.
Create packages/mcp-core/src/tools/catalog/your-tool-name.test.ts:
import { describe, it, expect } from "vitest";
import yourToolName from "./your-tool-name.js";
describe("your_tool_name", () => {
it("returns formatted output", async () => {
const result = await yourToolName.handler(
{ organizationSlug: "test-org", yourParam: "value" },
{
accessToken: "test-token",
userId: "1",
organizationSlug: null,
},
);
expect(result).toMatchInlineSnapshot(`
"# Results in **test-org**
Expected output here"
`);
});
});Testing Requirements:
- Input validation (see ../testing/overview.md)
- Error handling (use patterns from error-handling.md)
- Output formatting with snapshots
- At least one happy-path test must snapshot the full formatted handler
response with
toMatchInlineSnapshot(); partialtoContain()assertions are supplemental only - Review snapshots against tool-responses.md, including checks for internal IDs, raw JSON, empty placeholders, and user-facing labels
- API integration with MSW mocks
After changing output, update snapshots:
cd packages/mcp-core
pnpm vitest --run -uIn packages/mcp-server-mocks/src/handlers/:
{
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);
}
}See api-patterns.md for validation examples.
describeEval("your-tool", {
data: async () => [
{
input: `Primary use case in ${FIXTURES.organizationSlug}`,
expected: "Expected response",
},
// Maximum 2-3 scenarios!
],
task: TaskRunner(),
scorers: [Factuality()],
threshold: 0.6,
});# 1. Run unit tests
pnpm test tools.test
# 2. Test with inspector
pnpm inspector
# 3. Run minimal evals
pnpm eval your-tool- Tool module in
packages/mcp-core/src/tools/catalog/ - Tool registered in
packages/mcp-core/src/tools/catalog/index.ts - Co-located test includes a baseline inline snapshot for the tool output
- Direct exposure policy updated in
packages/mcp-core/src/tools/surfaces.tsif this should be top-level - Unit tests with snapshots
- Mock responses
- 1-2 eval tests (if critical)
-
outputSchemadeclared, or a reasoned skip entry in the metadata linter - Run quality checks
Some tools (the dataset search tools such as search_errors, plus search_issue_events and search_issues) embed
AI agents to normalize search parameters before the handler calls Sentry. Treat
the agent as a repair step for a structured request, not only as a natural
language query translator. The agent may rewrite the query string, but it may
also correct or fill related parameters such as dataset, fields, sort, and time
range when the provided combination would fail or produce the wrong result.
- Parameter repair - Fixing mismatched or incomplete search parameters
- Query normalization - Converting natural language or loose syntax to valid Sentry search syntax
- Dynamic field discovery - When available fields vary by project/context
- Semantic understanding - When the tool needs to understand intent across multiple parameters
- Simple API calls - Direct parameter mapping to API endpoints
- Deterministic operations - Operations with clear, unambiguous inputs
- Performance-critical paths - Embedded agents add latency and cost
// Tool handler delegates to embedded agent
async handler(params, context) {
const request = hasAgentProvider()
? await repairSearchParams({
query: params.query,
dataset: params.dataset,
fields: params.fields,
sort: params.sort,
statsPeriod: params.period,
})
: {
query: params.query,
dataset: params.dataset,
fields: params.fields,
sort: params.sort,
statsPeriod: params.period,
};
// Tool executes either the repaired request or the direct parameters.
const results = await apiService.searchEvents({
query: request.query,
dataset: request.dataset,
fields: request.fields,
sort: request.sort,
statsPeriod: request.statsPeriod,
});
return formatResults(results);
}Direct-capable tools should still work when no embedded agent provider is
available. Use hasAgentProvider() to decide whether to run the repair step.
If it returns false because API keys are missing, both OpenAI and Anthropic keys
are set without an explicit provider, or Azure OpenAI is missing a supported
base URL, execute the direct parameters as provided.
Do not silently fall back after a provider has been selected and the provider API
call fails. Invalid keys, deactivated accounts, rate limits, and other provider
4xx responses should become user-facing LLMProviderErrors from
callEmbeddedAgent(). That makes configuration/account problems visible instead
of hiding them behind an un-repaired direct search.
DO NOT retry internally. When the embedded agent fails:
- Throw a clear
UserInputErrororLLMProviderErrorwith specific guidance - Let the calling agent (Claude/Cursor) see the error
- The calling agent can retry with corrections if needed
IMPORTANT: Keep system prompts static to enable LLM provider caching. Never modify prompts based on errors.
// BAD: Dynamic prompt modification prevents caching
let systemPrompt = basePrompt;
if (previousError) {
systemPrompt += `\nPrevious error: ${previousError}`;
}
// GOOD: Static prompt with clear error boundaries
const systemPrompt = STATIC_SYSTEM_PROMPT;
try {
return await repairSearchParams(...);
} catch (error) {
throw new UserInputError(
`Could not repair search parameters: ${error.message}`,
);
}-
Embedded Agent Responsibilities:
- Repair or normalize structured search parameters
- Convert natural language to Sentry search syntax when needed
- Discover available fields/attributes
- Validate query syntax and parameter combinations
-
Tool Handler Responsibilities:
- Execute the repaired request
- Handle API errors
- Format results for the calling agent
-
Calling Agent Responsibilities:
- Decide when to use the tool
- Handle errors and retry if needed
- Interpret results
-
Create an AGENTS.md file in the tool directory documenting:
- The embedded agent's prompt and behavior
- Common repair and normalization patterns
- Known limitations
-
Keep agent prompts focused - Don't duplicate general MCP knowledge
-
Use structured outputs - Define clear schemas for agent responses, and follow the
structuredContentcontract in tool-responses.md -
Provide tool discovery - Let agents explore available fields dynamically
See packages/mcp-core/src/tools/catalog/search-events.ts and packages/mcp-core/src/tools/catalog/search-issues.ts for examples. Their helper code lives under packages/mcp-core/src/tools/support/.
Some tools may require access to Cloudflare Worker-specific bindings (like AutoRAG, D1, R2, etc.) that aren't available in the standard ServerContext. For these cases, create a separate endpoint in the Worker that the tool can call.
The search_docs tool demonstrates this pattern:
- Worker Route (
/api/search): Handles the actual AutoRAG interaction - MCP Tool: Makes HTTP requests to the Worker endpoint
- Authentication: Uses the same Bearer token for security
// In the Worker (routes/search.ts)
export default new Hono().post("/", async (c) => {
const { query, maxResults } = await c.req.json();
// Access Worker-specific bindings
const results = await c.env.AI.autorag("sentry-docs").aiSearch({
query,
max_num_results: maxResults,
});
return c.json({ results });
});
// In the MCP tool module
search_docs: async (context, params) => {
const response = await fetch(`${context.host}/api/search`, {
method: "POST",
headers: {
Authorization: `Bearer ${context.accessToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify(params),
});
const data = await response.json();
// Format and return results
};This pattern works with both Cloudflare-hosted and stdio transports.
- Error handling: error-handling.md
- API usage:
api-patterns.md - Testing: ../testing/overview.md
- Response policy: tool-responses.md
- Formatting patterns: common-patterns.md
- Tool examples:
packages/mcp-core/src/tools/catalog/ - Schema patterns:
packages/mcp-core/src/schema.ts - Mock examples:
packages/mcp-server-mocks/src/handlers/