feat(mcp): Serve each exposed CLI command as its own MCP tool

docs/architecture/overview.md

@@ -271,6 +271,18 @@ The same availability filters (skills, constraints, experimental mode, and
 required capabilities) apply before either direct registration or catalog
 execution.
 
+`sentry mcp --commands` (a preview) serves CLI commands instead of the
+catalog, through `packages/mcp-core/src/command-surface/`: every `exposed`
+command in the generated `command-catalog.json` is its own tool, named from
+its path (`sentry issue list` → `sentry_issue_list`), with the catalog's
+brief, examples, and parameter schema, and hints from its permission class.
+There is no search or execute meta-tool; harnesses search the tool list
+themselves. A call is checked against the command's schema and the
+session's constraints before a runner executes it. The stdio runner
+(`packages/cli/src/lib/mcp/command-surface.ts`) runs calls through
+`createSentrySDK().run()`; the hosted server will pass its own.
+`--read-only` drops the write tools.
+
 ### 6. Error Handling Philosophy
 
 Two-tier error system:

docs/operations/stdio-auth.md

@@ -131,7 +131,9 @@ until the server restarts.
 Routing is off when the credential is a static token (`SENTRY_AUTH_TOKEN`,
 `--access-token`, `SENTRY_ACCESS_TOKEN`): that token is the only account.
 `--organization-slug` (or an `<org>/` target) picks the account that knows the
-organization once, at startup, and every call uses it. To use accounts on
+organization once, at startup, and every call uses it. `--commands` does not
+route calls either: it uses the account that knows its `<org>/` target, else
+the startup account. To use accounts on
 different servers at once (say, sentry.io and a self-hosted server), configure
 one MCP server per host via `SENTRY_HOST`.
 

docs/operations/token-cost-tracking.md

@@ -43,6 +43,13 @@ Per-Tool Breakdown:
 ...
 ```
 
+**Measure the command surface** (`sentry mcp --commands`: one tool per
+exposed CLI command) instead of the tool catalog:
+
+```bash
+pnpm run measure-tokens -- --commands
+```
+
 **Write JSON to file:**
 
 ```bash

packages/cli/plugins/sentry-cli/skills/sentry-cli/references/mcp.md

@@ -29,6 +29,8 @@ Start a local Sentry MCP server
 - `--all-skills - Grant every active skill, including seer on self-hosted`
 - `--disable-skills <value> - Skills to remove, comma-separated`
 - `--experimental - Enable forward-looking tool variants and experimental features`
+- `--commands - Serve each CLI command as its own tool (sentry_issue_list, ...) instead of the tool catalog (preview)`
+- `--read-only - With --commands: list no write tools and refuse write calls`
 - `--agent-provider <value> - LLM provider for AI-powered search: openai, azure-openai, anthropic, or openrouter`
 - `--openai-base-url <value> - OpenAI API base URL`
 - `--openai-model <value> - OpenAI model (default: gpt-5)`
@@ -54,6 +56,9 @@ sentry mcp --all-skills
 # Grant only some skills
 sentry mcp --skills inspect,triage
 
+# Serve CLI commands instead of the tool catalog, read-only
+sentry mcp --commands --read-only
+
 # Pick the LLM provider for AI-powered search
 sentry mcp --agent-provider anthropic
 ```

packages/cli/src/commands/mcp.ts

@@ -115,6 +115,11 @@ export const mcpCommand = buildCommand({
         description: "Grant only some skills",
         command: "sentry mcp --skills inspect,triage",
       },
+      {
+        description:
+          "Serve CLI commands instead of the tool catalog, read-only",
+        command: "sentry mcp --commands --read-only",
+      },
       {
         description: "Pick the LLM provider for AI-powered search",
         command: "sentry mcp --agent-provider anthropic",
@@ -165,6 +170,12 @@ export const mcpCommand = buildCommand({
       experimental: booleanFlag(
         "Enable forward-looking tool variants and experimental features",
       ),
+      commands: booleanFlag(
+        "Serve each CLI command as its own tool (sentry_issue_list, ...) instead of the tool catalog (preview)",
+      ),
+      "read-only": booleanFlag(
+        "With --commands: list no write tools and refuse write calls",
+      ),
       "agent-provider": stringFlag(
         "LLM provider for AI-powered search: openai, azure-openai, anthropic, or openrouter",
       ),

packages/cli/src/lib/command-access.ts

@@ -1,8 +1,8 @@
 /**
  * What a command may do (permission class) and where agents may run it
- * (exposure). `sentry mcp` lists and runs commands by these fields:
- * `execute_sentry_read` runs only read commands, and hosts allowlist by
- * permission class (#1254). `check:command-access` keeps them honest.
+ * (exposure). `sentry mcp` lists and runs commands by these fields: its
+ * command tools carry hints from the permission class, which hosts allowlist
+ * by (#1254). `check:command-access` keeps them honest.
  */
 
 /**

packages/cli/src/lib/mcp.ts

@@ -440,13 +440,31 @@ export async function serveMcp(
   const { token, pin } = await withEnv(credentialEnv, () =>
     resolveMcpCredentialWithLogin(config),
   );
+
   // A static token (`--access-token`, `SENTRY_AUTH_TOKEN`) is the only
   // credential; a stored login can route calls to the other stored logins.
   const router =
     pin.kind === "stored" && !deprecatedToken
       ? createRouter(config, credentialEnv, pin)
       : undefined;
 
+  if (config.commands) {
+    // One account for the session: the stored login that knows
+    // `--organization-slug`, else the startup account. Calls are not routed
+    // between logins, and the router refreshes a token near expiry.
+    const target = { organizationSlug: config.organizationSlug ?? null };
+    const getToken = router
+      ? async () => (await router.resolve(target)).accessToken
+      : async () => token;
+    const { createCliCommandTools } = await import("./mcp/command-surface.js");
+    await serveMcpStdio(config, {
+      accessToken: await getToken(),
+      env,
+      tools: createCliCommandTools({ config, cwd, getToken }),
+    });
+    return;
+  }
+
   if (router && !config.organizationSlug) {
     await serveMcpStdio(config, {
       accessToken: token,

packages/cli/src/lib/mcp/args.ts

@@ -31,6 +31,10 @@ export type McpFlags = {
   readonly "all-skills": boolean;
   readonly "disable-skills"?: string;
   readonly experimental: boolean;
+  /** Serve CLI commands instead of the tool catalog. */
+  readonly commands: boolean;
+  /** With `--commands`: no write tool, and write calls are refused. */
+  readonly "read-only": boolean;
   readonly org?: string;
   readonly project?: string;
   /** Deprecated alias of `--org`. */
@@ -193,6 +197,8 @@ export type McpMergedArgs = {
   allSkills: boolean;
   disableSkills?: string;
   experimental: boolean;
+  commands: boolean;
+  readOnly: boolean;
   organizationSlug?: string;
   projectSlug?: string;
 };
@@ -248,6 +254,8 @@ export function mergeMcpArgs(
     allSkills: flags["all-skills"],
     disableSkills: flags["disable-skills"] ?? env.disableSkills,
     experimental: flags.experimental,
+    commands: flags.commands,
+    readOnly: flags["read-only"],
     organizationSlug: scopeFlag(flags, "org", "organization-slug", scope?.org),
     projectSlug: scopeFlag(flags, "project", "project-slug", scope?.project),
   };

packages/cli/src/lib/mcp/command-surface.ts

@@ -0,0 +1,66 @@
+/**
+ * `sentry mcp --commands`: serve each exposed CLI command as its own MCP tool
+ * through mcp-core's command surface.
+ *
+ * The tools come from the generated command catalog, and each call runs
+ * through `createSentrySDK().run()`, which loads only the top-level route the
+ * call runs, never the whole command tree.
+ *
+ * Loaded only in commands mode. `@sentry/mcp-server` does not bundle command
+ * handlers, so its bundle replaces this module with a stub.
+ */
+
+import {
+  type CommandCall,
+  CommandFailedError,
+  createCommandTools,
+  type ToolRegistry,
+  toCommandArgs,
+} from "@sentry/mcp-core/command-surface";
+import { createSentrySDK, SentryError } from "../../index.js";
+import type { McpServerConfig } from "./config.js";
+
+export type CommandSurfaceSetup = {
+  config: McpServerConfig;
+  /** Where commands run, for DSN detection and project roots. */
+  cwd: string;
+  /** The session's current token, refreshed as needed. */
+  getToken: () => Promise<string>;
+};
+
+/** Run one call through the CLI SDK, with JSON output and no telemetry of its own. */
+async function runCall(
+  setup: CommandSurfaceSetup,
+  call: CommandCall,
+): Promise<unknown> {
+  const { config } = setup;
+  const sdk = createSentrySDK({
+    token: await setup.getToken(),
+    url: `${config.sentryProtocol}://${config.sentryHost}`,
+    org: call.org,
+    project: call.project,
+    cwd: setup.cwd,
+    // The MCP server owns the process's Sentry client.
+    telemetry: false,
+  });
+  try {
+    // `run()` is typed for streaming flags too; the command surface refuses them.
+    return await (sdk.run(...toCommandArgs(call)) as Promise<unknown>);
+  } catch (error) {
+    if (error instanceof SentryError) {
+      throw new CommandFailedError(call.path.join(" "), error.message);
+    }
+    throw error;
+  }
+}
+
+/** The command surface's tools, running calls through the CLI SDK. */
+export function createCliCommandTools(
+  setup: CommandSurfaceSetup,
+): ToolRegistry {
+  return createCommandTools({
+    runtime: "stdio",
+    readOnly: setup.config.readOnly,
+    run: (call) => runCall(setup, call),
+  });
+}

packages/cli/src/lib/mcp/config.ts

@@ -40,6 +40,10 @@ export type McpServerConfig = {
   agentProvider?: McpAgentProvider;
   agentProviderFromFlag: boolean;
   experimental: boolean;
+  /** Serve each CLI command as its own tool instead of the tool catalog. */
+  commands: boolean;
+  /** With `commands`: list no write tools, and refuse write calls. */
+  readOnly: boolean;
   /** Skills granted for this session. */
   finalSkills: Set<Skill>;
   organizationSlug?: string;
@@ -173,6 +177,11 @@ export function finalizeMcpConfig(input: McpMergedArgs): McpServerConfig {
     );
   }
   const finalSkills = resolveSkills(input, sentryHost);
+  if (input.readOnly && !input.commands) {
+    throw new ValidationError(
+      "--read-only works only with --commands. To limit the tool catalog, pass --skills.",
+    );
+  }
 
   return {
     sentryHost,
@@ -192,6 +201,8 @@ export function finalizeMcpConfig(input: McpMergedArgs): McpServerConfig {
     agentProvider: resolveAgentProvider(input.agentProvider),
     agentProviderFromFlag: input.agentProviderFromFlag,
     experimental: input.experimental,
+    commands: input.commands,
+    readOnly: input.readOnly,
     finalSkills,
     organizationSlug: input.organizationSlug,
     projectSlug: input.projectSlug,

packages/cli/src/lib/mcp/server.ts

@@ -18,6 +18,7 @@ import {
 import { buildServer } from "@sentry/mcp-core/server";
 import { sentryBeforeSend } from "@sentry/mcp-core/telem/sentry";
 import { startStdio } from "@sentry/mcp-core/transports/stdio";
+import type { ToolRegistry } from "@sentry/mcp-core/command-surface";
 import type { CredentialRouter, ServerContext } from "@sentry/mcp-core/types";
 import { setServerVersion } from "@sentry/mcp-core/version";
 import {
@@ -59,6 +60,8 @@ export type McpServeOptions = {
    */
   credentialRouter?: CredentialRouter;
   env: NodeJS.ProcessEnv;
+  /** Tools to serve instead of the tool catalog (`--commands`). */
+  tools?: ToolRegistry;
 };
 
 const SENTRY_FLUSH_TIMEOUT_MS = 5000;
@@ -426,6 +429,7 @@ export async function serveMcpStdio(
   const server = buildServer({
     context,
     experimentalMode: config.experimental,
+    tools: options.tools,
   });
   const connection = await startStdio(server, context).catch(
     (error: unknown) => {