diff --git a/.agents/skills/verify-toolkit/SKILL.md b/.agents/skills/verify-toolkit/SKILL.md
index 799b77a47f..ada5bcf55d 100644
--- a/.agents/skills/verify-toolkit/SKILL.md
+++ b/.agents/skills/verify-toolkit/SKILL.md
@@ -89,6 +89,15 @@ node .agents/skills/verify-toolkit/scripts/check-results.mjs subset WIDE_DIR DIR
node .agents/skills/verify-toolkit/scripts/check-results.mjs local DIR
```
+`scripts/mcp-apps-host.mjs` acts as an MCP Apps host for
+`render_sentry_chart` on the mock server: it reads the tool's `ui://` view,
+mounts it in headless Chromium through the ext-apps `AppBridge`, and writes
+screenshots, `host-log.json`, and `checks.txt` to `--out`:
+
+```bash
+node .agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs --out DIR
+```
+
`scripts/sentry-offline.mjs` runs one CLI command with the same offline env,
and writes `command.txt`, `stdout.txt`, `stderr.txt`, and `exit-code.txt`:
diff --git a/.agents/skills/verify-toolkit/map/README.md b/.agents/skills/verify-toolkit/map/README.md
index 8ab5a451d5..54a2ad8a0b 100644
--- a/.agents/skills/verify-toolkit/map/README.md
+++ b/.agents/skills/verify-toolkit/map/README.md
@@ -57,5 +57,7 @@ out of the map.
- `mcp-access.md` covers who can start `sentry mcp` and what a session
reaches: login, skills, and org scope.
- `cli.md` covers CLI behavior with no login and with a token.
+- `mcp-apps.md` covers what an MCP Apps host gets for `render_sentry_chart`:
+ the `ui://` view, rendering, theme, and calls back through the host.
- `sentry-local.md` covers `sentry local`: verifying an app's SDK, querying a
retained session, hiding session credentials, and stopping the daemon.
diff --git a/.agents/skills/verify-toolkit/map/mcp-apps.md b/.agents/skills/verify-toolkit/map/mcp-apps.md
new file mode 100644
index 0000000000..fa63746853
--- /dev/null
+++ b/.agents/skills/verify-toolkit/map/mcp-apps.md
@@ -0,0 +1,44 @@
+# MCP Apps chart view
+
+What an MCP Apps host (Claude, VS Code, ChatGPT) gets for `render_sentry_chart`:
+the tool names a `ui://` view in `tools/list`, the view reads back as one
+self-contained HTML document, and the view renders the tool result, follows
+the host theme, and calls the tool again through the host. The goals are in
+`design/mcp-apps.md`.
+
+## Claims
+
+- `tool-meta` `render_sentry_chart` sets `_meta.ui.resourceUri` to a `ui://` URI and `_meta["openai/outputTemplate"]` to the same URI, with no deprecated flat `ui/resourceUri` key. Proof: `drive`.
+- `view-resource` `resources/list` lists that URI, and `resources/read` returns it with mime type `text/html;profile=mcp-app` and an HTML document. Proof: `drive`.
+- `view-listing` A session that cannot call `render_sentry_chart`, including every stable (non-experimental) session, lists no resources and no resources capability. Proof: `test` with `pnpm --filter @sentry/mcp-core exec vitest run src/server.ui-resources.test.ts`.
+- `view-renders` Mounted through the ext-apps AppBridge, which also checks the view's hand-written MCP Apps bridge against the reference host, the view draws the series, shows a tooltip on hover, and hides its empty state. Proof: `drive`.
+- `view-theme` The view follows the host's light or dark theme. Proof: `drive`.
+- `range-roundtrip` The range picker calls `render_sentry_chart` through the host with the new period and redraws without remounting. Proof: `drive`.
+- `open-link` "Open in Sentry" asks the host to open the result's Sentry URL with `ui/open-link`. Proof: `drive`.
+- `grouped` A `groupBy` result draws one series per top group, with a legend. Proof: `drive`.
+- `lifecycle` The view follows a `host-context-changed` theme change, shows a cancelled state on `ui/notifications/tool-cancelled`, and answers `ui/resource-teardown`. Proof: `drive`.
+- `default-csp` The view loads and runs under the spec's default CSP with no console errors, so it needs no `csp` domains. Proof: `drive`.
+
+## How to get to it
+
+- An MCP Apps host that lists `render_sentry_chart` and reads its `ui://` resource, over stdio (`sentry mcp --experimental`, `npx @sentry/mcp-server --experimental`) or remote HTTP in experimental mode. Stable sessions list neither the tool nor the view.
+- A host with no MCP Apps support gets the same tool with a text and structured result only.
+
+## Driving it with mcp-apps-host.mjs
+
+Preconditions:
+
+- Launch from `../SKILL.md` has run on this checkout, and `$VERIFY_RUN` is set.
+- A Chromium build for playwright-core is installed. If the script cannot launch it, run `pnpm --filter @sentry/mcp-core exec playwright-core install chromium-headless-shell`.
+
+- **Every `drive` claim: act as the host.** Run `node .agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs --out "$VERIFY_RUN/mcp-apps"`. It starts the mock server, calls the tool, reads the view, and mounts it in headless Chromium inside a host page that uses `AppBridge`. Every line it prints, also in `checks.txt`, is `PASS`. The screenshots `chart-light.png`, `chart-dark.png`, `chart-range-7d.png`, and `chart-grouped-dark.png` show each state. `host-log.json` holds the view's `tools/call` and `ui/open-link` requests to the host.
+
+## Gotchas
+
+- The mock server answers from built packages. Rerun `pnpm run build` after changing mcp-core or the mocks, or the script drives stale code.
+- The view is generated. After changing `packages/mcp-core/chart-app/`, run `pnpm --filter @sentry/mcp-core generate-chart-app`, then build.
+- The host page sets the default CSP with a meta tag in `srcdoc`. Real hosts serve the view from a sandbox origin with CSP headers.
+
+## Gaps
+
+- `real-hosts` Rendering in Claude, VS Code, ChatGPT, and Codex desktop needs those apps with a live server; this map drives only the reference AppBridge. Use `mcp-qa` for real hosts.
diff --git a/.agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs b/.agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs
new file mode 100644
index 0000000000..c322708d1f
--- /dev/null
+++ b/.agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs
@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+// Act as an MCP Apps host for render_sentry_chart, with no LLM: start the mock
+// stdio server, call the tool, read its `ui://` view, and mount the view in a
+// headless browser through the ext-apps AppBridge, the way Claude or VS Code
+// does. Screenshots the chart in light and dark, after the range picker calls
+// the tool again through the host, and split by an attribute. Writes evidence
+// and one PASS or FAIL line per check to checks.txt in --out. See ../SKILL.md.
+import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { offlineEnv } from "./offline-env.mjs";
+
+const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
+const argv = process.argv.slice(2);
+const out = argv[argv.indexOf("--out") + 1];
+if (!argv.includes("--out") || !out) {
+ console.error("usage: mcp-apps-host.mjs --out DIR");
+ process.exit(2);
+}
+mkdirSync(out, { recursive: true });
+
+// The MCP client SDK is a dependency of the test client; esbuild, the
+// AppBridge, and playwright-core are dev dependencies of mcp-core.
+const fromClient = createRequire(
+ join(repo, "packages/mcp-test-client/package.json"),
+);
+const fromCore = createRequire(join(repo, "packages/mcp-core/package.json"));
+const load = (require, id) => import(pathToFileURL(require.resolve(id)).href);
+const { Client } = await load(
+ fromClient,
+ "@modelcontextprotocol/sdk/client/index.js",
+);
+const { StdioClientTransport } = await load(
+ fromClient,
+ "@modelcontextprotocol/sdk/client/stdio.js",
+);
+const { build } = await load(fromCore, "esbuild");
+const { chromium } = fromCore("playwright-core");
+
+const TOOL = "render_sentry_chart";
+const ORG = "sentry-mcp-evals";
+const ERRORS_CHART = {
+ organizationSlug: ORG,
+ dataset: "errors",
+ query: "level:error",
+ yAxis: "count()",
+ period: "24h",
+};
+const GROUPED_CHART = {
+ organizationSlug: ORG,
+ dataset: "spans",
+ query: "is_transaction:true",
+ yAxis: "p95(span.duration)",
+ groupBy: "release",
+ period: "7d",
+};
+// The spec's default view CSP: no network, no eval.
+const DEFAULT_CSP =
+ "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; media-src 'self' data:; connect-src 'none'";
+
+const write = (name, value) =>
+ writeFileSync(
+ join(out, name),
+ typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`,
+ );
+let failures = 0;
+function check(id, ok, detail) {
+ const line = `${ok ? "PASS" : "FAIL"} mcp-apps#${id}: ${detail}`;
+ if (!ok) failures++;
+ console.log(line);
+ appendFileSync(join(out, "checks.txt"), `${line}\n`);
+}
+
+// A minimal host page: mounts the view in a sandboxed iframe under the
+// default CSP and bridges it with AppBridge. Tool calls from the view go to
+// Node (window.mcpCallTool), which forwards them to the real server.
+const hostScript = (
+ await build({
+ stdin: {
+ resolveDir: join(repo, "packages/mcp-core"),
+ contents: `
+ import { AppBridge, PostMessageTransport } from "@modelcontextprotocol/ext-apps/app-bridge";
+ window.hostLog = [];
+ window.mountView = async ({ html, theme, toolArgs, toolResult }) => {
+ document.body.dataset.theme = theme;
+ const iframe = document.createElement("iframe");
+ iframe.setAttribute("sandbox", "allow-scripts");
+ document.getElementById("host").replaceChildren(iframe);
+ const bridge = new AppBridge(
+ null,
+ { name: "verify-toolkit host", version: "0.0.0" },
+ { openLinks: {}, serverTools: {} },
+ { hostContext: { theme, locale: "en-US", timeZone: "UTC", platform: "web", displayMode: "inline", containerDimensions: { width: 720, maxHeight: 900 } } },
+ );
+ bridge.oncalltool = async (params) => {
+ window.hostLog.push({ method: "tools/call", params });
+ return await window.mcpCallTool(params);
+ };
+ bridge.onopenlink = async (params) => {
+ window.hostLog.push({ method: "ui/open-link", params });
+ return {};
+ };
+ bridge.onsizechange = ({ height }) => {
+ if (height) iframe.style.height = height + "px";
+ };
+ window.bridge = bridge;
+ const initialized = new Promise((done) => { bridge.oninitialized = done; });
+ await bridge.connect(new PostMessageTransport(iframe.contentWindow, iframe.contentWindow));
+ iframe.srcdoc = html.replace("
", ${JSON.stringify(``)});
+ await initialized;
+ await bridge.sendToolInput({ arguments: toolArgs });
+ await bridge.sendToolResult(toolResult);
+ };
+ `,
+ },
+ bundle: true,
+ format: "iife",
+ write: false,
+ })
+).outputFiles[0].text;
+const hostPage = ``;
+
+const { env, cleanup } = offlineEnv({ token: true });
+delete env.SENTRY_HOST;
+const transport = new StdioClientTransport({
+ command: process.execPath,
+ args: [
+ "--experimental-strip-types",
+ "--import",
+ join(repo, "scripts/strip-types-resolve.mjs"),
+ join(repo, "packages/mcp-server-evals/src/bin/start-mock-stdio.ts"),
+ ],
+ env,
+ cwd: repo,
+ stderr: "pipe",
+});
+let stderr = "";
+transport.stderr?.on("data", (chunk) => {
+ stderr += chunk;
+});
+const client = new Client({
+ name: "verify-toolkit-apps-host",
+ version: "0.0.0",
+});
+let browser;
+try {
+ await client.connect(transport);
+ const { tools } = await client.listTools();
+ const tool = tools.find((t) => t.name === TOOL);
+ write("tool.json", tool ?? null);
+ const uri = tool?._meta?.ui?.resourceUri;
+ check(
+ "tool-meta",
+ typeof uri === "string" &&
+ uri.startsWith("ui://") &&
+ tool._meta["openai/outputTemplate"] === uri &&
+ !("ui/resourceUri" in tool._meta),
+ `${TOOL} _meta.ui.resourceUri=${uri}, openai/outputTemplate=${tool?._meta?.["openai/outputTemplate"]}`,
+ );
+
+ const { resources } = await client.listResources();
+ const { contents } = await client.readResource({ uri });
+ const view = contents[0];
+ write("resources-list.json", resources);
+ write("resource-read.json", {
+ ...view,
+ text: `<${view?.text?.length ?? 0} chars, see view.html>`,
+ });
+ write("view.html", view?.text ?? "");
+ check(
+ "view-resource",
+ resources.some((r) => r.uri === uri) &&
+ view?.mimeType === "text/html;profile=mcp-app" &&
+ view.text.startsWith(""),
+ `resources/read ${uri}: ${view?.mimeType}, ${Math.round((view?.text?.length ?? 0) / 1024)} KiB HTML`,
+ );
+
+ const calls = [];
+ const callTool = async (params) => {
+ const result = await client.callTool(params);
+ calls.push({ request: params, result });
+ return result;
+ };
+ const errorsResult = await callTool({ name: TOOL, arguments: ERRORS_CHART });
+ const groupedResult = await callTool({
+ name: TOOL,
+ arguments: GROUPED_CHART,
+ });
+
+ browser = await chromium.launch();
+ const page = await browser.newPage({
+ viewport: { width: 768, height: 520 },
+ deviceScaleFactor: 2,
+ });
+ const consoleErrors = [];
+ page.on("console", (msg) => {
+ if (msg.type() === "error") consoleErrors.push(msg.text());
+ });
+ await page.exposeFunction("mcpCallTool", callTool);
+ await page.setContent(hostPage);
+ const frame = page.frameLocator("iframe");
+ const mount = async (theme, toolArgs, toolResult) => {
+ await page.evaluate((input) => window.mountView(input), {
+ html: view.text,
+ theme,
+ toolArgs,
+ toolResult,
+ });
+ await frame.locator("svg path").first().waitFor();
+ // Let the view report its size and the host resize the iframe.
+ await page.waitForTimeout(300);
+ };
+ const shot = async (name) => {
+ await page.locator("#host").screenshot({ path: join(out, name) });
+ return join(out, name);
+ };
+
+ await mount("light", ERRORS_CHART, errorsResult);
+ const svgBox = await frame.locator("svg").boundingBox();
+ await page.mouse.move(
+ svgBox.x + svgBox.width * 0.7,
+ svgBox.y + svgBox.height / 2,
+ );
+ const tooltip = await frame.locator(".tooltip").innerText();
+ const light = await shot("chart-light.png");
+ const lightBg = await frame
+ .locator("body")
+ .evaluate((el) => getComputedStyle(el).backgroundColor);
+ const emptyHidden = await frame.locator(".state").isHidden();
+ check(
+ "view-renders",
+ tooltip.includes("count()") && emptyHidden,
+ `light chart with hover tooltip "${tooltip.replace(/\s+/g, " ")}" -> ${light}`,
+ );
+
+ await mount("dark", ERRORS_CHART, errorsResult);
+ const darkBg = await frame
+ .locator("body")
+ .evaluate((el) => getComputedStyle(el).backgroundColor);
+ const dark = await shot("chart-dark.png");
+ check(
+ "view-theme",
+ lightBg !== darkBg,
+ `host theme light=${lightBg} dark=${darkBg} -> ${dark}`,
+ );
+
+ await mount("light", ERRORS_CHART, errorsResult);
+ const before = await frame.locator(".subtitle").innerText();
+ await frame.getByRole("button", { name: "7d", exact: true }).click();
+ await frame.locator(".subtitle", { hasText: "Last 7 days" }).waitFor();
+ await frame.locator('.chart[data-loading="false"]').waitFor();
+ const range = await shot("chart-range-7d.png");
+ const hostLog = await page.evaluate(() => window.hostLog);
+ const rangeCall = hostLog.find((entry) => entry.method === "tools/call");
+ const rangeResult = calls.at(-1);
+ check(
+ "range-roundtrip",
+ rangeCall?.params?.name === TOOL &&
+ rangeCall.params.arguments.period === "7d" &&
+ rangeResult?.result?.structuredContent?.timeRange?.statsPeriod === "7d",
+ `"${before}" -> view called ${TOOL} period=7d through the host, got ${rangeResult?.result?.structuredContent?.series?.[0]?.buckets?.length} buckets -> ${range}`,
+ );
+
+ await frame.getByRole("button", { name: "Open in Sentry" }).click();
+ await page.waitForFunction(() =>
+ window.hostLog.some((e) => e.method === "ui/open-link"),
+ );
+ const openLink = (await page.evaluate(() => window.hostLog)).find(
+ (e) => e.method === "ui/open-link",
+ );
+ check(
+ "open-link",
+ openLink?.params?.url?.startsWith(`https://${ORG}.sentry.io/`),
+ `ui/open-link ${openLink?.params?.url}`,
+ );
+
+ await mount("dark", GROUPED_CHART, groupedResult);
+ const legend = await frame.locator(".legend").innerText();
+ const grouped = await shot("chart-grouped-dark.png");
+ check(
+ "grouped",
+ legend.split("\n").filter(Boolean).length === 3,
+ `top groups "${legend.replace(/\n/g, " | ")}" -> ${grouped}`,
+ );
+
+ // The rest of the lifecycle: a theme change, a cancelled call, teardown.
+ await page.evaluate(() =>
+ window.bridge.sendHostContextChange({ theme: "light" }),
+ );
+ await frame
+ .locator("html[data-theme='light']")
+ .waitFor({ state: "attached" });
+ await page.evaluate(() =>
+ window.bridge.sendToolCancelled({ reason: "verify-toolkit" }),
+ );
+ const cancelled = await frame.locator(".state.error").innerText();
+ const teardown = await page.evaluate(() =>
+ window.bridge.teardownResource({ reason: "verify-toolkit" }),
+ );
+ check(
+ "lifecycle",
+ cancelled.includes("cancelled") && JSON.stringify(teardown) === "{}",
+ `host-context-changed -> light, tool-cancelled -> "${cancelled}", ui/resource-teardown -> ${JSON.stringify(teardown)}`,
+ );
+
+ write("host-log.json", await page.evaluate(() => window.hostLog));
+ write("calls.json", calls);
+ write("console-errors.json", consoleErrors);
+ check(
+ "default-csp",
+ consoleErrors.length === 0,
+ `${consoleErrors.length} console errors under the default CSP`,
+ );
+} catch (error) {
+ check(
+ "host-run",
+ false,
+ error instanceof Error ? (error.stack ?? error.message) : String(error),
+ );
+} finally {
+ await browser?.close();
+ await client.close().catch(() => {});
+ cleanup();
+ writeFileSync(join(out, "server-stderr.txt"), stderr);
+}
+process.exit(failures > 0 ? 1 : 0);
diff --git a/.github/workflows/token-cost.yml b/.github/workflows/token-cost.yml
index 86a98b29af..711299dd34 100644
--- a/.github/workflows/token-cost.yml
+++ b/.github/workflows/token-cost.yml
@@ -14,6 +14,11 @@ on:
- "packages/mcp-core/src/internal/tool-helpers/tool-call-formatting.ts"
- "packages/mcp-core/scripts/measure-token-cost.ts"
- "packages/mcp-core/scripts/generate-definitions.ts"
+ - "packages/mcp-core/chart-app/**"
+ - "packages/mcp-core/src/ui/**"
+ - "packages/mcp-core/src/ui-resources.ts"
+ - "packages/mcp-core/scripts/generate-chart-app.ts"
+ - "packages/mcp-core/scripts/measure-ui-views.ts"
- "package.json"
- "pnpm-lock.yaml"
- "pnpm-workspace.yaml"
@@ -29,6 +34,11 @@ on:
- "packages/mcp-core/src/internal/tool-helpers/tool-call-formatting.ts"
- "packages/mcp-core/scripts/measure-token-cost.ts"
- "packages/mcp-core/scripts/generate-definitions.ts"
+ - "packages/mcp-core/chart-app/**"
+ - "packages/mcp-core/src/ui/**"
+ - "packages/mcp-core/src/ui-resources.ts"
+ - "packages/mcp-core/scripts/generate-chart-app.ts"
+ - "packages/mcp-core/scripts/measure-ui-views.ts"
- "package.json"
- "pnpm-lock.yaml"
- "pnpm-workspace.yaml"
@@ -126,6 +136,10 @@ jobs:
# Save for summary
cat token-report.md >> $GITHUB_STEP_SUMMARY
+ - name: Measure MCP Apps views
+ working-directory: packages/mcp-core
+ run: pnpm run measure-ui -- -o ui-stats.json --markdown token-report.md --markdown "$GITHUB_STEP_SUMMARY"
+
- name: Download main branch token stats
if: github.event_name == 'pull_request'
uses: dawidd6/action-download-artifact@v6
@@ -246,10 +260,11 @@ jobs:
details_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
});
- - name: Comment on PR if token count changed
+ - name: Comment on PR
uses: actions/github-script@v7
- # Skip for fork PRs (no write permissions)
- if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && steps.compare.outputs.has_comparison == 'true' && steps.compare.outputs.delta != '0'
+ # Skip for fork PRs (no write permissions). Posts on every run, since
+ # a view can change while the tool token count stays the same.
+ if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
continue-on-error: true # Don't fail workflow if comment creation fails
with:
script: |
@@ -290,5 +305,7 @@ jobs:
if: always()
with:
name: token-stats-${{ github.sha }}
- path: packages/mcp-core/token-stats.json
+ path: |
+ packages/mcp-core/token-stats.json
+ packages/mcp-core/ui-stats.json
retention-days: 90
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index 39e40ef1b8..b27ad9c221 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -12,6 +12,7 @@
"packages/cli/CHANGELOG.md",
"packages/cli/AGENTS.md",
"packages/mcp-server-mocks/src/fixtures/**",
+ "packages/mcp-core/src/ui/chart-app.generated.ts",
"packages/codemod-cli3to4/tests/**",
"**/worker-configuration.d.ts",
"**/tsconfig*.json"
diff --git a/.oxlintrc.json b/.oxlintrc.json
index d39013caec..2962949c1a 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -13,6 +13,7 @@
"**/worker-configuration.d.ts",
"**/tsconfig*.json",
"packages/mcp-server-mocks/src/fixtures/**",
+ "packages/mcp-core/src/ui/chart-app.generated.ts",
"packages/codemod-cli3to4/tests/**"
],
"rules": {
@@ -130,12 +131,20 @@
{
"name": "sentry",
"message": "mcp-core and toolkit-core must not import the Sentry CLI. Inject CLI-only capabilities through interfaces defined in mcp-core or toolkit-core (see docs/architecture/overview.md#package-dependency-direction)."
+ },
+ {
+ "name": "@modelcontextprotocol/ext-apps",
+ "message": "mcp-core and its MCP Apps views speak MCP Apps directly (src/ui-resources.ts, chart-app/bridge.ts), so the server bundle and the views stay small. ext-apps is a dev dependency for the verify-toolkit host only (see design/mcp-apps.md)."
}
],
"patterns": [
{
"group": ["sentry/**", "**/cli/src/**", "**/packages/cli/**"],
"message": "mcp-core and toolkit-core must not import the Sentry CLI. Inject CLI-only capabilities through interfaces defined in mcp-core or toolkit-core (see docs/architecture/overview.md#package-dependency-direction)."
+ },
+ {
+ "group": ["@modelcontextprotocol/ext-apps/**"],
+ "message": "mcp-core and its MCP Apps views speak MCP Apps directly (src/ui-resources.ts, chart-app/bridge.ts), so the server bundle and the views stay small. ext-apps is a dev dependency for the verify-toolkit host only (see design/mcp-apps.md)."
}
]
}
@@ -398,6 +407,10 @@
"group": ["sentry/**", "**/cli/src/**", "**/packages/cli/**"],
"message": "mcp-core and toolkit-core must not import the Sentry CLI. Inject CLI-only capabilities through interfaces defined in mcp-core or toolkit-core (see docs/architecture/overview.md#package-dependency-direction)."
},
+ {
+ "group": ["@modelcontextprotocol/ext-apps/**"],
+ "message": "mcp-core and its MCP Apps views speak MCP Apps directly (src/ui-resources.ts, chart-app/bridge.ts), so the server bundle and the views stay small. ext-apps is a dev dependency for the verify-toolkit host only (see design/mcp-apps.md)."
+ },
{
"group": ["node:*"],
"message": "Shared toolkit-core modules must run in browsers. Use web-standard APIs, or inject the host-specific piece."
diff --git a/design/README.md b/design/README.md
index bc361c45d8..92ba6c3a26 100644
--- a/design/README.md
+++ b/design/README.md
@@ -34,6 +34,7 @@ such as `automations#run-now`, and do not restate it.
- [MCP tools](./mcp-tools.md): the Sentry tools an agent can list and call, and how it finds the right one.
- [MCP tool responses](./mcp-tool-responses.md): what a tool result gives an agent to answer a Sentry question.
+- [MCP Apps views](./mcp-apps.md): interactive views that MCP Apps hosts render inline for a tool result.
- [MCP access](./mcp-access.md): who can use Sentry MCP, over which transport, and what a session can reach.
- [Sentry CLI](./sentry-cli.md): the `sentry` command for people and agents in a terminal.
- [Sentry Local](./sentry-local.md): the app telemetry `sentry local` captures on a developer's machine, with no account.
diff --git a/design/mcp-apps.md b/design/mcp-apps.md
new file mode 100644
index 0000000000..7fb1a01ce0
--- /dev/null
+++ b/design/mcp-apps.md
@@ -0,0 +1,73 @@
+# MCP Apps views
+
+A host that supports MCP Apps, such as Claude or VS Code, renders a Sentry
+tool result as an interactive view inline in the conversation. Every other
+client gets the same answer as text.
+
+## Intent
+
+- A view is an optional enhancement. A tool with a view gives every client
+ the complete answer, so a text-only client or a host without MCP Apps loses
+ nothing but the picture.
+- The model never relays data to a view. A tool with a view takes a query,
+ and the server fetches the data from Sentry, so what the view shows comes
+ from Sentry, not from model output.
+- A view costs a session nothing until a host renders it, and little when
+ one does. Views speak the MCP Apps protocol directly, with no SDK or schema
+ library, so adding one barely grows the server.
+- A view is safe in any host's sandbox. It trusts nothing that it receives
+ and reaches nothing outside the host.
+
+## Entry points
+
+- The `render_sentry_chart` chart in an MCP Apps host, with its range picker
+ and Open in Sentry button, in experimental sessions.
+- `ui://` resources in `resources/list` and `resources/read`, named by a
+ tool's `_meta.ui.resourceUri` (and `openai/outputTemplate` for ChatGPT).
+
+## Rules
+
+- MCP Apps ship in experimental sessions only, until real hosts are
+ verified. A tool with a view is marked `experimental`, so a stable
+ session lists neither the tool nor its view, and skill prompts do not
+ advertise it.
+- A tool with a view is listed for every client that can call it, and its
+ result is the same for every client. A view shows nothing that the result
+ does not hold.
+- A tool with a view takes a query, not values. Follow-up calls from the
+ view, such as a new time range, call the same tool through the host.
+- A view is one self-contained HTML document with inline scripts and
+ styles. Its declared CSP lists no origins, and it loads nothing from the
+ network: no remote scripts, styles, fonts, or images, and no requests.
+- Each view has a byte budget, and the build fails when the view exceeds
+ it. The chart's budget is 24 KiB.
+- A view's `ui://` URI carries a version, and any change to the view's HTML
+ ships under a new version, because hosts cache views by URI.
+- A view treats the tool result and every host message as untrusted. It
+ parses the result into its own shape at the boundary, shows an error state
+ instead of drawing data in the wrong shape, and writes text only as text.
+- A session lists a view only when it lists a tool that names it. A session
+ with no such tool declares no resources capability.
+- Views are not gated on the client advertising MCP Apps support
+ (`capabilities.extensions["io.modelcontextprotocol/ui"]`). The remote
+ server builds a new session for each HTTP request, so it cannot see what
+ the client sent in `initialize` when it answers `tools/list`. Gating there
+ would hide views from Claude, VS Code, and ChatGPT, which all advertise
+ support. Hosts that render without advertising, such as the ext-apps
+ reference host, would also lose them. Instead, the server loads a view's
+ HTML only when a host reads the view, so a text-only session never loads
+ it.
+- A view follows the host's theme, locale, and time zone.
+
+## Gaps
+
+- Rendering is proven only against the ext-apps reference host
+ (`mcp-apps#real-hosts`). Claude, VS Code, ChatGPT, and Codex are not
+ verified, so "every MCP Apps host renders the view" is unproven.
+- The spec says servers SHOULD check client capabilities before they list
+ UI tools. Sessions that cannot render, such as the Codex and Goose CLIs,
+ still get `_meta.ui` and a listed view. They never load its HTML. This
+ falls short of "costs a session nothing" by one tool `_meta` key and one
+ resource entry. Gating can follow once the remote server sees client
+ capabilities on each request, as the draft protocol's per-request
+ capabilities allow.
diff --git a/design/mcp-tool-responses.md b/design/mcp-tool-responses.md
index cd5a0e5da4..ac692fa36f 100644
--- a/design/mcp-tool-responses.md
+++ b/design/mcp-tool-responses.md
@@ -26,6 +26,8 @@ question, in Sentry's own terms, without reading upstream API payloads.
- Response notes and side quests: short tips at the end of a result, such as
a pagination cursor or source maps that failed to apply.
- Feedback suggestions that point at `submit_feedback_to_sentry_team`.
+- MCP Apps views, which render a tool's structured content inline in hosts
+ that support them. They follow [MCP Apps views](./mcp-apps.md).
## Rules
diff --git a/design/mcp-tools.md b/design/mcp-tools.md
index 79cf5834d3..37bddb56ef 100644
--- a/design/mcp-tools.md
+++ b/design/mcp-tools.md
@@ -32,6 +32,9 @@ harness the user already works in, such as Claude Code, Codex, or Cursor.
that are not stable yet.
- `search_sentry_tools` and `execute_sentry_tool`, only on the fallback
gateway surface.
+- MCP Apps views, which follow [MCP Apps views](./mcp-apps.md).
+ `render_sentry_chart` is the one tool with a view, and it is
+ experimental.
## Rules
diff --git a/docs/contributing/adding-tools.md b/docs/contributing/adding-tools.md
index 618cf14a85..d51bc578e6 100644
--- a/docs/contributing/adding-tools.md
+++ b/docs/contributing/adding-tools.md
@@ -264,6 +264,10 @@ particular:
See [common-patterns.md](common-patterns.md#response-formatting) for shared
formatting patterns and examples.
+To render a result inline in MCP Apps hosts, see
+[tool-responses.md](tool-responses.md#mcp-apps-views). A view is optional:
+the tool still answers in full for every other client.
+
## Step 3: Add Tests
Follow comprehensive testing patterns from [../testing/overview.md](../testing/overview.md) for unit, integration, and evaluation tests.
diff --git a/docs/contributing/tool-responses.md b/docs/contributing/tool-responses.md
index 6c47e210ef..477168f47a 100644
--- a/docs/contributing/tool-responses.md
+++ b/docs/contributing/tool-responses.md
@@ -232,6 +232,34 @@ experimental sessions first stays pending until it graduates. The PR that
makes an entry stale also deletes it. To add a `_meta` key, add it to `ALLOWED_TOOL_META`
with a comment that says which client reads it.
+## MCP Apps Views
+
+A tool can name an inline view for hosts that support
+[MCP Apps](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx).
+The rules a view follows are in
+[design/mcp-apps.md](../../design/mcp-apps.md). `render_sentry_chart` is the
+example:
+
+- The view is a `UiResource` in `packages/mcp-core/src/ui-resources.ts`: a
+ versioned `ui://` URI, the `htmlSha256` of its HTML, and a `loadHtml()` that
+ imports the generated module on the first `resources/read`.
+- The tool sets `_meta: uiToolMeta(resource)`, which writes
+ `_meta.ui.resourceUri` for MCP Apps hosts and `openai/outputTemplate` for
+ ChatGPT. Add both keys to `ALLOWED_TOOL_META`.
+- The view source lives in `packages/mcp-core/chart-app/`. `bridge.ts` is the
+ MCP Apps protocol over `postMessage`, and `parse.ts` parses
+ `structuredContent` into the chart type (`parse.test.ts` keeps it in step
+ with the tool's output schema). Do not import `@modelcontextprotocol/ext-apps`
+ or zod there; Oxlint rejects the first, and the budget rejects the second.
+- Run `pnpm --filter @sentry/mcp-core generate-chart-app` after changing the
+ view. It and `ci:policy` fail when the view is over its budget or loads
+ anything from the network, and `ci:policy` fails when the generated file is
+ stale. `src/ui-resources.test.ts` then fails until you bump the URI version
+ and set the new `htmlSha256` it prints.
+- Prove a view with `.agents/skills/verify-toolkit/map/mcp-apps.md`, which
+ mounts it through the ext-apps `AppBridge` in headless Chromium. That run is
+ also the conformance check for `bridge.ts`.
+
## Suggested Actions
Use `suggestedActions` when a tool result reveals a concrete follow-up tool call
diff --git a/docs/evidence/mcp-apps-chart/chart-dark.png b/docs/evidence/mcp-apps-chart/chart-dark.png
new file mode 100644
index 0000000000..746cd8d2e6
Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-dark.png differ
diff --git a/docs/evidence/mcp-apps-chart/chart-grouped-dark.png b/docs/evidence/mcp-apps-chart/chart-grouped-dark.png
new file mode 100644
index 0000000000..72831ff1ef
Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-grouped-dark.png differ
diff --git a/docs/evidence/mcp-apps-chart/chart-light.png b/docs/evidence/mcp-apps-chart/chart-light.png
new file mode 100644
index 0000000000..6f1ebd6f14
Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-light.png differ
diff --git a/docs/evidence/mcp-apps-chart/chart-range-7d.png b/docs/evidence/mcp-apps-chart/chart-range-7d.png
new file mode 100644
index 0000000000..0ac5ab1e1d
Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-range-7d.png differ
diff --git a/docs/evidence/mcp-apps-chart/checks.txt b/docs/evidence/mcp-apps-chart/checks.txt
new file mode 100644
index 0000000000..5a6fcdf08e
--- /dev/null
+++ b/docs/evidence/mcp-apps-chart/checks.txt
@@ -0,0 +1,9 @@
+PASS mcp-apps#tool-meta: render_sentry_chart _meta.ui.resourceUri=ui://sentry/chart/v1.html, openai/outputTemplate=ui://sentry/chart/v1.html
+PASS mcp-apps#view-resource: resources/read ui://sentry/chart/v1.html: text/html;profile=mcp-app, 16 KiB HTML
+PASS mcp-apps#view-renders: light chart with hover tooltip "Sep 10, 16:00 UTC count() 91" -> docs/evidence/mcp-apps-chart/chart-light.png
+PASS mcp-apps#view-theme: host theme light=rgb(255, 255, 255) dark=rgb(30, 26, 37) -> docs/evidence/mcp-apps-chart/chart-dark.png
+PASS mcp-apps#range-roundtrip: "errors · level:error · Last 24 hours" -> view called render_sentry_chart period=7d through the host, got 56 buckets -> docs/evidence/mcp-apps-chart/chart-range-7d.png
+PASS mcp-apps#open-link: ui/open-link https://sentry-mcp-evals.sentry.io/explore/discover/homepage/?dataset=errors&queryDataset=error-events&query=level%3Aerror&project=-1&field=count%28%29&sort=-count%28%29&statsPeriod=7d&mode=aggregate&yAxis=count%28%29
+PASS mcp-apps#grouped: top groups "frontend@2.4.1 | frontend@2.4.0 | frontend@2.3.9" -> docs/evidence/mcp-apps-chart/chart-grouped-dark.png
+PASS mcp-apps#lifecycle: host-context-changed -> light, tool-cancelled -> "The chart request was cancelled.", ui/resource-teardown -> {}
+PASS mcp-apps#default-csp: 0 console errors under the default CSP
diff --git a/docs/operations/token-cost-tracking.md b/docs/operations/token-cost-tracking.md
index c3d2a22d06..182140682b 100644
--- a/docs/operations/token-cost-tracking.md
+++ b/docs/operations/token-cost-tracking.md
@@ -86,6 +86,26 @@ GitHub Actions workflow runs on every PR and push to main:
**Workflow:** `.github/workflows/token-cost.yml`
+## MCP Apps View Size
+
+The same workflow measures each MCP Apps view, the `ui://` HTML that a host
+such as Claude, VS Code, or ChatGPT downloads to render a tool result. The
+script builds the server with every skill, lists its resources, and reads each
+`ui://` resource through `resources/read`, so a new view shows up without a
+script change.
+
+```bash
+pnpm --filter @sentry/mcp-core measure-ui # Display
+pnpm --filter @sentry/mcp-core measure-ui -- -o ui-stats.json # Write JSON
+```
+
+Per view it reports raw, gzip (level 9), and brotli (quality 11) bytes, and raw
+bytes as a percentage of the view's `budgetBytes` in `src/ui-resources.ts`.
+The report adds an "MCP Apps views" section to the PR comment and job summary,
+and `ui-stats.json` goes into the `token-stats-{sha}` artifact. The budget is
+enforced by the view's generator, such as `generate-chart-app`, not by this
+report; see [design/mcp-apps.md](../../design/mcp-apps.md).
+
## Understanding the Results
Run `pnpm run measure-tokens` for current numbers; the examples above are a
diff --git a/packages/mcp-core/chart-app/bridge.ts b/packages/mcp-core/chart-app/bridge.ts
new file mode 100644
index 0000000000..fed4286693
--- /dev/null
+++ b/packages/mcp-core/chart-app/bridge.ts
@@ -0,0 +1,249 @@
+/**
+ * The view side of MCP Apps: JSON-RPC 2.0 over `postMessage` with the host.
+ * Covers only what the chart view uses, so the view ships without zod or an
+ * MCP client SDK.
+ *
+ * Spec: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+ */
+
+/** The stable spec version this view speaks. */
+const PROTOCOL_VERSION = "2026-01-26";
+const REQUEST_TIMEOUT_MS = 60_000;
+
+type JsonRpcId = string | number;
+
+interface JsonRpcError {
+ code: number;
+ message: string;
+ data?: unknown;
+}
+
+/** One message on the wire, in either direction. */
+type JsonRpcMessage =
+ | { jsonrpc: "2.0"; id: JsonRpcId; method: string; params?: unknown }
+ | { jsonrpc: "2.0"; method: string; params?: unknown }
+ | { jsonrpc: "2.0"; id: JsonRpcId; result: unknown }
+ | { jsonrpc: "2.0"; id: JsonRpcId | null; error: JsonRpcError };
+
+/** The fields of the spec's `HostContext` that the view reads. */
+export interface HostContext {
+ theme?: "light" | "dark";
+ styles?: { variables?: Record };
+ locale?: string;
+ timeZone?: string;
+}
+
+interface ContentBlock {
+ type: string;
+ text?: string;
+}
+
+/** An MCP `CallToolResult`. `structuredContent` is untrusted. */
+export interface CallToolResult {
+ content: ContentBlock[];
+ structuredContent?: unknown;
+ isError?: boolean;
+}
+
+interface ViewHandlers {
+ /** `ui/notifications/tool-input`: the complete tool arguments. */
+ toolInput?(args: Record): void;
+ /** `ui/notifications/tool-result` */
+ toolResult?(result: CallToolResult): void;
+ /** `ui/notifications/tool-cancelled` */
+ toolCancelled?(reason: string | undefined): void;
+ /** The initial context and each `host-context-changed`, merged. */
+ hostContext?(context: HostContext): void;
+ /** `ui/resource-teardown`, answered once this returns. */
+ teardown?(): void;
+}
+
+export interface Host {
+ /** `tools/call`, proxied by the host to the MCP server. */
+ callTool(
+ name: string,
+ args: Record,
+ ): Promise;
+ /** `ui/open-link` */
+ openLink(url: string): Promise;
+}
+
+const isObject = (value: unknown): value is Record =>
+ typeof value === "object" && value !== null && !Array.isArray(value);
+
+function toCallToolResult(params: unknown): CallToolResult {
+ const result = isObject(params) ? params : {};
+ const content = Array.isArray(result["content"])
+ ? result["content"].filter(
+ (block): block is ContentBlock =>
+ isObject(block) &&
+ typeof block["type"] === "string" &&
+ (block["text"] === undefined || typeof block["text"] === "string"),
+ )
+ : [];
+ return {
+ content,
+ structuredContent: result["structuredContent"],
+ isError: result["isError"] === true,
+ };
+}
+
+/**
+ * Runs the `ui/initialize` handshake, sends `ui/notifications/initialized`,
+ * then reports the view's size whenever it changes. Messages from any window
+ * other than `host` are ignored.
+ */
+export async function connect(
+ appInfo: { name: string; version: string },
+ handlers: ViewHandlers,
+ host: Window = window.parent,
+): Promise {
+ let nextId = 1;
+ let context: HostContext = {};
+ const pending = new Map<
+ JsonRpcId,
+ { resolve(result: unknown): void; reject(error: Error): void }
+ >();
+ const send = (message: JsonRpcMessage) => host.postMessage(message, "*");
+
+ function request(method: string, params: unknown): Promise {
+ const id = nextId++;
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ pending.delete(id);
+ reject(new Error(`${method} timed out`));
+ }, REQUEST_TIMEOUT_MS);
+ pending.set(id, {
+ resolve: (result) => {
+ clearTimeout(timer);
+ resolve(result);
+ },
+ reject: (error) => {
+ clearTimeout(timer);
+ reject(error);
+ },
+ });
+ send({ jsonrpc: "2.0", id, method, params });
+ });
+ }
+
+ function updateContext(partial: unknown): void {
+ if (!isObject(partial)) return;
+ context = { ...context, ...partial };
+ handlers.hostContext?.(context);
+ }
+
+ function onNotification(method: string, params: unknown): void {
+ const values = isObject(params) ? params : {};
+ switch (method) {
+ case "ui/notifications/tool-input":
+ handlers.toolInput?.(
+ isObject(values["arguments"]) ? values["arguments"] : {},
+ );
+ return;
+ case "ui/notifications/tool-result":
+ handlers.toolResult?.(toCallToolResult(params));
+ return;
+ case "ui/notifications/tool-cancelled":
+ handlers.toolCancelled?.(
+ typeof values["reason"] === "string" ? values["reason"] : undefined,
+ );
+ return;
+ case "ui/notifications/host-context-changed":
+ updateContext(params);
+ return;
+ }
+ // Other notifications, such as tool-input-partial, need nothing here.
+ }
+
+ function onRequest(id: JsonRpcId, method: string): void {
+ if (method === "ui/resource-teardown") handlers.teardown?.();
+ if (method === "ui/resource-teardown" || method === "ping") {
+ send({ jsonrpc: "2.0", id, result: {} });
+ return;
+ }
+ send({
+ jsonrpc: "2.0",
+ id,
+ error: { code: -32601, message: `Method not found: ${method}` },
+ });
+ }
+
+ window.addEventListener("message", (event: MessageEvent) => {
+ const message = event.data;
+ if (event.source !== host || !isObject(message)) return;
+ if (message["jsonrpc"] !== "2.0") return;
+ const { id, method } = message;
+ const hasId = typeof id === "string" || typeof id === "number";
+ if (typeof method === "string") {
+ if (hasId) onRequest(id, method);
+ else onNotification(method, message["params"]);
+ return;
+ }
+ const waiter = hasId ? pending.get(id) : undefined;
+ if (!hasId || !waiter) return;
+ pending.delete(id);
+ const error = message["error"];
+ if (isObject(error)) {
+ waiter.reject(
+ new Error(
+ typeof error["message"] === "string"
+ ? error["message"]
+ : "The host could not complete the request.",
+ ),
+ );
+ } else {
+ waiter.resolve(message["result"]);
+ }
+ });
+
+ const initialized = await request("ui/initialize", {
+ appInfo,
+ appCapabilities: {},
+ protocolVersion: PROTOCOL_VERSION,
+ });
+ updateContext(isObject(initialized) ? initialized["hostContext"] : undefined);
+ send({ jsonrpc: "2.0", method: "ui/notifications/initialized" });
+ reportSize(send);
+
+ return {
+ callTool: async (name, args) =>
+ toCallToolResult(await request("tools/call", { name, arguments: args })),
+ openLink: async (url) => {
+ await request("ui/open-link", { url });
+ },
+ };
+}
+
+/** Sends `ui/notifications/size-changed` once per frame when the size changes. */
+function reportSize(send: (message: JsonRpcMessage) => void): void {
+ let scheduled = false;
+ let width = 0;
+ let height = 0;
+ const measure = () => {
+ if (scheduled) return;
+ scheduled = true;
+ requestAnimationFrame(() => {
+ scheduled = false;
+ const root = document.documentElement;
+ // Measure the content, not a height the host gave the iframe.
+ const previous = root.style.height;
+ root.style.height = "max-content";
+ const nextHeight = Math.ceil(root.getBoundingClientRect().height);
+ root.style.height = previous;
+ const nextWidth = Math.ceil(window.innerWidth);
+ if (nextWidth === width && nextHeight === height) return;
+ width = nextWidth;
+ height = nextHeight;
+ send({
+ jsonrpc: "2.0",
+ method: "ui/notifications/size-changed",
+ params: { width, height },
+ });
+ });
+ };
+ measure();
+ const observer = new ResizeObserver(measure);
+ observer.observe(document.documentElement);
+ observer.observe(document.body);
+}
diff --git a/packages/mcp-core/chart-app/chart.test.ts b/packages/mcp-core/chart-app/chart.test.ts
new file mode 100644
index 0000000000..0cac024ad4
--- /dev/null
+++ b/packages/mcp-core/chart-app/chart.test.ts
@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { scaleFraction, valueScale } from "./chart";
+
+function plotted(values: number[]) {
+ const scale = valueScale(values);
+ return {
+ scale,
+ fractions: values.map((value) => scaleFraction(scale, value)),
+ baseline: scaleFraction(scale, 0),
+ };
+}
+
+describe("valueScale", () => {
+ it("keeps all-negative series inside the plot, with 0 at the top", () => {
+ const { scale, fractions, baseline } = plotted([-4, -2]);
+
+ expect(scale).toEqual({ bottom: -4, top: 0, step: 1 });
+ for (const fraction of fractions) {
+ expect(fraction).toBeGreaterThanOrEqual(0);
+ expect(fraction).toBeLessThanOrEqual(1);
+ }
+ expect(baseline).toBe(1);
+ });
+
+ it("spans mixed-sign series with the 0 baseline between them", () => {
+ const { scale, fractions, baseline } = plotted([-30, 5, 70]);
+
+ expect(scale.bottom).toBeLessThanOrEqual(-30);
+ expect(scale.top).toBeGreaterThanOrEqual(70);
+ for (const fraction of fractions) {
+ expect(fraction).toBeGreaterThanOrEqual(0);
+ expect(fraction).toBeLessThanOrEqual(1);
+ }
+ expect(baseline).toBeGreaterThan(fractions[0] ?? 0);
+ expect(baseline).toBeLessThan(fractions[2] ?? 1);
+ });
+
+ it("puts 0 at the bottom of an all-positive series", () => {
+ const { scale, baseline } = plotted([56, 140]);
+
+ expect(scale).toEqual({ bottom: 0, top: 150, step: 50 });
+ expect(baseline).toBe(0);
+ });
+
+ it("gives an all-zero series a one-step domain", () => {
+ expect(valueScale([0, 0])).toEqual({ bottom: 0, top: 1, step: 1 });
+ });
+});
diff --git a/packages/mcp-core/chart-app/chart.ts b/packages/mcp-core/chart-app/chart.ts
new file mode 100644
index 0000000000..071e16b015
--- /dev/null
+++ b/packages/mcp-core/chart-app/chart.ts
@@ -0,0 +1,379 @@
+/**
+ * Draws a render_sentry_chart result as SVG: one area (or line, when there
+ * are several series) per series, a y grid, time labels, a hatched band over
+ * buckets that are still filling, and a hover tooltip. Values come from an
+ * untrusted tool result, so text only ever goes in through textContent.
+ */
+import type { ChartResult } from "../src/tools/support/chart/schema";
+
+const SVG_NS = "http://www.w3.org/2000/svg";
+const HEIGHT = 220;
+const MARGIN = { top: 8, right: 8, bottom: 22, left: 48 };
+export const SERIES_COLORS = [
+ "#7553ff",
+ "#f2b712",
+ "#ff45a8",
+ "#3fb68b",
+ "#2ba1db",
+];
+
+const DURATION_MS: Record = {
+ nanosecond: 1e-6,
+ microsecond: 1e-3,
+ millisecond: 1,
+ second: 1000,
+ minute: 60_000,
+ hour: 3_600_000,
+};
+const SIZE_UNITS = ["B", "KB", "MB", "GB", "TB"];
+
+const compact = new Intl.NumberFormat(undefined, {
+ notation: "compact",
+ maximumFractionDigits: 1,
+});
+
+export function formatValue(value: number, chart: ChartResult): string {
+ if (chart.valueType === "duration") {
+ const ms = value * (DURATION_MS[chart.valueUnit ?? "millisecond"] ?? 1);
+ if (Math.abs(ms) < 1000) return `${Number(ms.toFixed(1))}ms`;
+ if (Math.abs(ms) < 60_000) return `${Number((ms / 1000).toFixed(2))}s`;
+ return `${Number((ms / 60_000).toFixed(1))}min`;
+ }
+ if (chart.valueType === "percentage") {
+ return `${Number((value * 100).toFixed(2))}%`;
+ }
+ if (chart.valueType === "size") {
+ let size = value;
+ let unit = 0;
+ while (Math.abs(size) >= 1024 && unit < SIZE_UNITS.length - 1) {
+ size /= 1024;
+ unit++;
+ }
+ return `${Number(size.toFixed(1))} ${SIZE_UNITS[unit]}`;
+ }
+ return compact.format(value);
+}
+
+function svg(
+ tag: K,
+ attrs: Record,
+ parent?: Element,
+): SVGElementTagNameMap[K] {
+ const el = document.createElementNS(SVG_NS, tag);
+ for (const [key, value] of Object.entries(attrs)) {
+ el.setAttribute(key, String(value));
+ }
+ parent?.appendChild(el);
+ return el;
+}
+
+/** Round step for about `count` gridlines across `range`. */
+function niceStep(range: number, count: number): number {
+ const raw = range / count;
+ const magnitude = 10 ** Math.floor(Math.log10(raw));
+ const factor = [1, 2, 2.5, 5, 10].find((f) => f * magnitude >= raw) ?? 10;
+ return factor * magnitude;
+}
+
+export interface TimeFormat {
+ locale: string | undefined;
+ timeZone: string | undefined;
+}
+
+function timeFormatter(spanMs: number, format: TimeFormat) {
+ return new Intl.DateTimeFormat(format.locale, {
+ timeZone: format.timeZone,
+ ...(spanMs <= 2 * 86_400_000
+ ? { hour: "2-digit", minute: "2-digit", hourCycle: "h23" }
+ : { month: "short", day: "numeric" }),
+ });
+}
+
+export function formatTooltipTime(time: number, format: TimeFormat): string {
+ return new Intl.DateTimeFormat(format.locale, {
+ timeZone: format.timeZone,
+ month: "short",
+ day: "numeric",
+ hour: "2-digit",
+ minute: "2-digit",
+ hourCycle: "h23",
+ timeZoneName: "short",
+ }).format(time);
+}
+
+export interface ValueScale {
+ bottom: number;
+ top: number;
+ step: number;
+}
+
+/**
+ * The y domain for `values`: round gridline steps from `bottom` to `top`,
+ * always including 0 so the baseline is on the chart, whether the values
+ * are positive, negative, or both.
+ */
+export function valueScale(values: readonly number[]): ValueScale {
+ const min = Math.min(0, ...values);
+ const max = Math.max(0, ...values);
+ const step = max > min ? niceStep(max - min, 4) : 1;
+ // `|| 0` turns -0 into 0, so the bottom label never reads "-0".
+ const bottom = Math.floor(min / step) * step || 0;
+ const top = Math.max(bottom + step, Math.ceil(max / step) * step);
+ return { bottom, top, step };
+}
+
+/** Where `value` sits in `scale`: 0 at the bottom of the plot, 1 at the top. */
+export function scaleFraction(scale: ValueScale, value: number): number {
+ return (value - scale.bottom) / (scale.top - scale.bottom);
+}
+
+/** Renders the chart into `container`, replacing what was there. */
+export function drawChart(
+ container: HTMLElement,
+ chart: ChartResult,
+ format: TimeFormat,
+): void {
+ container.replaceChildren();
+ const width = Math.max(container.clientWidth, 280);
+ const plotWidth = width - MARGIN.left - MARGIN.right;
+ const plotHeight = HEIGHT - MARGIN.top - MARGIN.bottom;
+ const times = chart.series[0]?.buckets.map((b) => Date.parse(b.time)) ?? [];
+ const first = times[0] ?? 0;
+ const last = times.at(-1) ?? first;
+ const span = Math.max(last - first, 1);
+ const scale = valueScale(
+ chart.series.flatMap((s) => s.buckets.map((b) => b.value)),
+ );
+ const { bottom, top, step } = scale;
+ const x = (time: number) =>
+ MARGIN.left +
+ (times.length > 1 ? ((time - first) / span) * plotWidth : plotWidth / 2);
+ const y = (value: number) =>
+ MARGIN.top + plotHeight - scaleFraction(scale, value) * plotHeight;
+
+ const root = svg("svg", {
+ viewBox: `0 0 ${width} ${HEIGHT}`,
+ height: HEIGHT,
+ role: "img",
+ "aria-label": chart.title,
+ });
+ const defs = svg("defs", {}, root);
+ const hatch = svg(
+ "pattern",
+ {
+ id: "incomplete-hatch",
+ width: 6,
+ height: 6,
+ patternUnits: "userSpaceOnUse",
+ patternTransform: "rotate(45)",
+ },
+ defs,
+ );
+ svg("line", { x1: 0, y1: 0, x2: 0, y2: 6, "stroke-width": 2 }, hatch);
+
+ const grid = svg("g", { class: "grid axis" }, root);
+ const gridlines = Math.round((top - bottom) / step);
+ for (let i = 0; i <= gridlines; i++) {
+ const value = bottom + i * step;
+ svg(
+ "line",
+ { x1: MARGIN.left, x2: width - MARGIN.right, y1: y(value), y2: y(value) },
+ grid,
+ );
+ const label = svg(
+ "text",
+ { x: MARGIN.left - 6, y: y(value) + 4, "text-anchor": "end" },
+ grid,
+ );
+ label.textContent = formatValue(value, chart);
+ }
+
+ const ticks = svg("g", { class: "axis" }, root);
+ const tickFormat = timeFormatter(span, format);
+ const tickCount = Math.min(
+ times.length,
+ Math.max(2, Math.floor(plotWidth / 90)),
+ );
+ for (let i = 0; i < tickCount; i++) {
+ const time = first + (span * i) / Math.max(tickCount - 1, 1);
+ const label = svg(
+ "text",
+ {
+ x: x(time),
+ y: HEIGHT - 6,
+ "text-anchor":
+ i === 0 ? "start" : i === tickCount - 1 ? "end" : "middle",
+ },
+ ticks,
+ );
+ label.textContent = tickFormat.format(time);
+ }
+
+ // Buckets still filling: a hatched band from the first one to the end.
+ const firstFilling = chart.series[0]?.buckets.findIndex((b) => b.incomplete);
+ if (firstFilling !== undefined && firstFilling >= 0) {
+ const fillingStart = x(times[Math.max(firstFilling - 1, 0)] ?? last);
+ svg(
+ "rect",
+ {
+ class: "incomplete-band",
+ x: fillingStart,
+ y: MARGIN.top,
+ width: Math.max(x(last) - fillingStart, 2),
+ height: plotHeight,
+ },
+ root,
+ );
+ }
+ svg(
+ "line",
+ {
+ class: "baseline",
+ x1: MARGIN.left,
+ x2: width - MARGIN.right,
+ y1: y(0),
+ y2: y(0),
+ },
+ root,
+ );
+
+ const single = chart.series.length === 1;
+ chart.series.forEach((series, index) => {
+ const color = SERIES_COLORS[index % SERIES_COLORS.length] ?? "#7553ff";
+ const points = series.buckets.map(
+ (b) => [x(Date.parse(b.time)), y(b.value)] as const,
+ );
+ const split = series.buckets.findIndex((b) => b.incomplete);
+ const settled = split < 0 ? points : points.slice(0, Math.max(split, 1));
+ const filling = split < 0 ? [] : points.slice(Math.max(split - 1, 0));
+ const path = (pts: readonly (readonly [number, number])[]) =>
+ pts.map(([px, py], i) => `${i ? "L" : "M"}${px},${py}`).join("");
+ if (single && points.length > 1) {
+ svg(
+ "path",
+ {
+ d: `${path(points)}L${points.at(-1)?.[0]},${y(0)}L${points[0]?.[0]},${y(0)}Z`,
+ fill: color,
+ "fill-opacity": 0.16,
+ },
+ root,
+ );
+ }
+ svg(
+ "path",
+ { d: path(settled), fill: "none", stroke: color, "stroke-width": 2 },
+ root,
+ );
+ if (points.length === 1) {
+ const [px, py] = points[0] ?? [0, 0];
+ svg("circle", { cx: px, cy: py, r: 4, fill: color }, root);
+ }
+ if (filling.length > 1) {
+ svg(
+ "path",
+ {
+ d: path(filling),
+ fill: "none",
+ stroke: color,
+ "stroke-width": 2,
+ "stroke-dasharray": "4 3",
+ },
+ root,
+ );
+ }
+ });
+
+ const crosshair = svg(
+ "line",
+ {
+ class: "crosshair",
+ y1: MARGIN.top,
+ y2: MARGIN.top + plotHeight,
+ visibility: "hidden",
+ },
+ root,
+ );
+ const markers = chart.series.map((_, index) =>
+ svg(
+ "circle",
+ {
+ r: 3.5,
+ fill: SERIES_COLORS[index % SERIES_COLORS.length] ?? "#7553ff",
+ visibility: "hidden",
+ },
+ root,
+ ),
+ );
+ container.appendChild(root);
+
+ const tooltip = document.createElement("div");
+ tooltip.className = "tooltip";
+ tooltip.hidden = true;
+ container.appendChild(tooltip);
+
+ const hide = () => {
+ tooltip.hidden = true;
+ crosshair.setAttribute("visibility", "hidden");
+ for (const marker of markers) marker.setAttribute("visibility", "hidden");
+ };
+ const showAt = (index: number) => {
+ const time = times[index];
+ if (time === undefined) return hide();
+ const px = x(time);
+ crosshair.setAttribute("x1", String(px));
+ crosshair.setAttribute("x2", String(px));
+ crosshair.setAttribute("visibility", "visible");
+ const timeRow = document.createElement("div");
+ timeRow.className = "time";
+ const incomplete = chart.series[0]?.buckets[index]?.incomplete;
+ timeRow.textContent = `${formatTooltipTime(time, format)}${incomplete ? " (still filling)" : ""}`;
+ const rows = chart.series.map((series, s) => {
+ const bucket = series.buckets[index];
+ const marker = markers[s];
+ if (bucket && marker) {
+ marker.setAttribute("cx", String(px));
+ marker.setAttribute("cy", String(y(bucket.value)));
+ marker.setAttribute("visibility", "visible");
+ }
+ const row = document.createElement("div");
+ row.className = "row";
+ const swatch = document.createElement("span");
+ swatch.className = "swatch";
+ swatch.style.background = SERIES_COLORS[s % SERIES_COLORS.length] ?? "";
+ const label = document.createElement("span");
+ label.textContent = series.label;
+ const value = document.createElement("span");
+ value.textContent = bucket ? formatValue(bucket.value, chart) : "–";
+ row.append(swatch, label, value);
+ return row;
+ });
+ tooltip.replaceChildren(timeRow, ...rows);
+ tooltip.hidden = false;
+ // The tooltip is HTML, so convert viewBox units to CSS pixels. They
+ // differ when the container is narrower than the minimum viewBox width.
+ const box = root.getBoundingClientRect();
+ const toCss = box.width > 0 ? box.width / width : 1;
+ const cssX = px * toCss;
+ const tipWidth = tooltip.offsetWidth;
+ const left = Math.min(cssX + 12, box.width - tipWidth - 4);
+ tooltip.style.left = `${left < cssX && cssX - tipWidth - 12 > 0 ? cssX - tipWidth - 12 : Math.max(left, 0)}px`;
+ tooltip.style.top = `${MARGIN.top * toCss}px`;
+ };
+
+ root.addEventListener("pointermove", (event) => {
+ const box = root.getBoundingClientRect();
+ const px = ((event.clientX - box.left) / box.width) * width;
+ if (px < MARGIN.left || px > width - MARGIN.right || times.length === 0) {
+ return hide();
+ }
+ const time = first + ((px - MARGIN.left) / plotWidth) * span;
+ let nearest = 0;
+ times.forEach((t, i) => {
+ if (Math.abs(t - time) < Math.abs((times[nearest] ?? 0) - time)) {
+ nearest = i;
+ }
+ });
+ showAt(nearest);
+ });
+ root.addEventListener("pointerleave", hide);
+}
diff --git a/packages/mcp-core/chart-app/main.ts b/packages/mcp-core/chart-app/main.ts
new file mode 100644
index 0000000000..3194dc91ae
--- /dev/null
+++ b/packages/mcp-core/chart-app/main.ts
@@ -0,0 +1,312 @@
+/**
+ * The render_sentry_chart view. The host sends the tool's arguments and
+ * result; the range picker calls the tool again through the host and redraws
+ * in place.
+ */
+import type { ChartResult } from "../src/tools/support/chart/schema";
+import {
+ type CallToolResult,
+ connect,
+ type Host,
+ type HostContext,
+} from "./bridge";
+import {
+ drawChart,
+ formatTooltipTime,
+ formatValue,
+ SERIES_COLORS,
+ type TimeFormat,
+} from "./chart";
+import { parseChartResult } from "./parse";
+
+const TOOL_NAME = "render_sentry_chart";
+const RANGES = ["1h", "24h", "7d", "14d"] as const;
+const UNIT_NAMES: Record = {
+ m: "minute",
+ h: "hour",
+ d: "day",
+ w: "week",
+};
+
+type View =
+ | { kind: "waiting" }
+ | { kind: "ready"; chart: ChartResult }
+ | { kind: "error"; message: string; chart: ChartResult | null };
+
+let view: View = { kind: "waiting" };
+let toolArgs: Record = {};
+let pendingRange: string | null = null;
+let format: TimeFormat = { locale: undefined, timeZone: undefined };
+
+function el(
+ tag: K,
+ className?: string,
+ text?: string,
+): HTMLElementTagNameMap[K] {
+ const node = document.createElement(tag);
+ if (className) node.className = className;
+ if (text !== undefined) node.textContent = text;
+ return node;
+}
+
+const title = el("h1", undefined, "Sentry chart");
+const subtitle = el("div", "subtitle");
+const ranges = el("div", "ranges");
+const openButton = el("button", "open", "Open in Sentry");
+const stats = el("div", "stats");
+const chartBox = el("div", "chart");
+const legend = el("div", "legend");
+const note = el("div", "note");
+const state = el("div", "state", "Loading chart…");
+const rangeButtons = RANGES.map((range) => {
+ const button = el("button", undefined, range);
+ button.type = "button";
+ button.addEventListener("click", () => void changeRange(range));
+ ranges.appendChild(button);
+ return button;
+});
+
+const header = el("header");
+const heading = el("div");
+heading.append(title, subtitle);
+const controls = el("div", "controls");
+controls.append(ranges, openButton);
+header.append(heading, controls);
+const main = el("main");
+main.append(header, stats, chartBox, legend, note, state);
+document.body.appendChild(main);
+
+function rangeLabel(chart: ChartResult): string {
+ const { statsPeriod, start, end } = chart.timeRange;
+ const match = statsPeriod ? /^(\d+)([mhdw])$/.exec(statsPeriod) : null;
+ if (match?.[1] && match[2]) {
+ const count = Number(match[1]);
+ const unit = UNIT_NAMES[match[2]] ?? match[2];
+ return `Last ${count === 1 ? unit : `${count} ${unit}s`}`;
+ }
+ if (start && end) {
+ return `${formatTooltipTime(Date.parse(start), format)} – ${formatTooltipTime(Date.parse(end), format)}`;
+ }
+ return statsPeriod ?? "";
+}
+
+function stat(label: string, value: string): HTMLElement {
+ const item = el("span", undefined, `${label} `);
+ item.appendChild(el("strong", undefined, value));
+ return item;
+}
+
+// Self-hosted Sentry can serve plain http, including localhost.
+function isWebUrl(url: string | undefined): url is string {
+ if (!url) return false;
+ try {
+ const { protocol } = new URL(url);
+ return protocol === "https:" || protocol === "http:";
+ } catch {
+ return false;
+ }
+}
+
+function render(): void {
+ const chart = view.kind === "waiting" ? null : view.chart;
+ const busy = pendingRange !== null;
+ chartBox.dataset["loading"] = String(busy);
+ for (const [index, button] of rangeButtons.entries()) {
+ const range = RANGES[index];
+ button.disabled = busy || chart === null;
+ button.setAttribute(
+ "aria-pressed",
+ String((pendingRange ?? chart?.timeRange.statsPeriod) === range),
+ );
+ }
+ openButton.disabled = !isWebUrl(chart?.url);
+
+ if (view.kind === "error") {
+ state.hidden = false;
+ state.className = "state error";
+ state.textContent = view.message;
+ }
+ if (!chart) {
+ if (view.kind === "waiting") state.hidden = false;
+ stats.replaceChildren();
+ legend.replaceChildren();
+ chartBox.replaceChildren();
+ note.textContent = "";
+ return;
+ }
+
+ title.textContent = chart.title;
+ subtitle.replaceChildren(
+ `${chart.dataset} · `,
+ el("code", undefined, chart.query || "all events"),
+ ` · ${rangeLabel(chart)}`,
+ );
+
+ const hasData = chart.series.some((series) => series.buckets.length > 0);
+ if (view.kind === "ready") {
+ state.className = "state";
+ state.hidden = hasData;
+ state.textContent = "No data for this query in this range.";
+ }
+
+ const single = chart.series.length === 1 ? chart.series[0] : undefined;
+ const items: HTMLElement[] = [];
+ if (single?.total != null) {
+ items.push(stat("Total", formatValue(single.total, chart)));
+ }
+ if (chart.peak) {
+ items.push(
+ stat(
+ "Peak",
+ `${formatValue(chart.peak.value, chart)}${single ? "" : ` (${chart.peak.series})`} at ${formatTooltipTime(Date.parse(chart.peak.time), format)}`,
+ ),
+ );
+ }
+ if (hasData) items.push(stat("Interval", chart.interval));
+ stats.replaceChildren(...items);
+
+ legend.replaceChildren(
+ ...(single
+ ? []
+ : chart.series.map((series, index) => {
+ const item = el("span", "item");
+ const swatch = el("span", "swatch");
+ swatch.style.background =
+ SERIES_COLORS[index % SERIES_COLORS.length] ?? "";
+ const total =
+ series.total === null
+ ? ""
+ : ` · ${formatValue(series.total, chart)}`;
+ item.append(swatch, `${series.label}${total}`);
+ return item;
+ })),
+ );
+
+ const filling = chart.series.some((series) =>
+ series.buckets.some((bucket) => bucket.incomplete),
+ );
+ const ingestion =
+ chart.ingestion && chart.ingestion.status !== "healthy"
+ ? ` Ingestion is ${chart.ingestion.status}.`
+ : "";
+ note.textContent = hasData
+ ? `${filling ? "Hatched area: buckets still receiving data." : ""}${ingestion}`.trim()
+ : "";
+
+ if (hasData) {
+ drawChart(chartBox, chart, format);
+ } else {
+ chartBox.replaceChildren();
+ }
+}
+
+function errorText(result: CallToolResult): string {
+ const text = result.content.find((block) => block.type === "text")?.text;
+ return text ?? "The chart could not load.";
+}
+
+function showResult(result: CallToolResult): void {
+ const previous = view.kind === "waiting" ? null : view.chart;
+ if (result.isError) {
+ view = { kind: "error", message: errorText(result), chart: previous };
+ return;
+ }
+ const chart = parseChartResult(result.structuredContent);
+ view = chart
+ ? { kind: "ready", chart }
+ : {
+ kind: "error",
+ message: "The chart data was not in the expected shape.",
+ chart: previous,
+ };
+}
+
+let host: Host | null = null;
+
+async function changeRange(range: string): Promise {
+ const args: Record = {
+ ...toolArgs,
+ period: range,
+ start: null,
+ end: null,
+ };
+ // A fixed bucket size may not fit the new range, so let Sentry pick.
+ delete args["interval"];
+ if (!host) return;
+ pendingRange = range;
+ render();
+ try {
+ const result = await host.callTool(TOOL_NAME, args);
+ if (!result.isError) toolArgs = args;
+ showResult(result);
+ } catch (error) {
+ view = {
+ kind: "error",
+ message: error instanceof Error ? error.message : String(error),
+ chart: view.kind === "waiting" ? null : view.chart,
+ };
+ } finally {
+ pendingRange = null;
+ render();
+ }
+}
+
+function applyHostContext(context: HostContext): void {
+ const root = document.documentElement;
+ if (context.theme === "light" || context.theme === "dark") {
+ root.dataset["theme"] = context.theme;
+ root.style.colorScheme = context.theme;
+ }
+ for (const [name, value] of Object.entries(context.styles?.variables ?? {})) {
+ if (name.startsWith("--") && typeof value === "string") {
+ root.style.setProperty(name, value);
+ }
+ }
+ if (context.locale || context.timeZone) {
+ format = {
+ locale: context.locale ?? format.locale,
+ timeZone: context.timeZone ?? format.timeZone,
+ };
+ }
+ render();
+}
+
+openButton.addEventListener("click", () => {
+ const chart = view.kind === "waiting" ? null : view.chart;
+ if (chart && isWebUrl(chart.url)) void host?.openLink(chart.url);
+});
+
+let lastWidth = 0;
+new ResizeObserver(([entry]) => {
+ const width = Math.round(entry?.contentRect.width ?? 0);
+ if (width !== lastWidth && view.kind !== "waiting") {
+ lastWidth = width;
+ render();
+ }
+}).observe(main);
+
+render();
+void connect(
+ { name: "Sentry chart", version: "1.0.0" },
+ {
+ toolInput: (args) => {
+ toolArgs = { ...args };
+ },
+ toolResult: (result) => {
+ showResult(result);
+ render();
+ },
+ toolCancelled: () => {
+ view = {
+ kind: "error",
+ message: "The chart request was cancelled.",
+ chart: view.kind === "waiting" ? null : view.chart,
+ };
+ pendingRange = null;
+ render();
+ },
+ hostContext: applyHostContext,
+ },
+).then((connected) => {
+ host = connected;
+});
diff --git a/packages/mcp-core/chart-app/parse.test.ts b/packages/mcp-core/chart-app/parse.test.ts
new file mode 100644
index 0000000000..be2ec4b3c7
--- /dev/null
+++ b/packages/mcp-core/chart-app/parse.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from "vitest";
+import { renderSentryChartOutputSchema } from "../src/tools/support/chart/schema";
+import { parseChartResult } from "./parse";
+
+const chart = {
+ title: "count() of level:error",
+ dataset: "errors",
+ query: "level:error",
+ yAxis: "count()",
+ groupBy: "release",
+ valueType: "integer",
+ valueUnit: null,
+ interval: "1h",
+ timeRange: { statsPeriod: "24h", start: null, end: null },
+ url: "https://sentry-mcp-evals.sentry.io/explore/discover/homepage/",
+ series: [
+ {
+ label: "1.0.0",
+ total: 12,
+ buckets: [
+ {
+ time: "2025-09-10T23:00:00.000Z",
+ value: 12,
+ incomplete: false,
+ outsideRetention: false,
+ },
+ ],
+ },
+ { label: "1.0.1", total: null, buckets: [] },
+ ],
+ peak: { series: "1.0.0", time: "2025-09-10T23:00:00.000Z", value: 12 },
+ ingestion: {
+ status: "healthy",
+ delaySeconds: null,
+ completeThrough: "2025-09-10T23:30:00.000Z",
+ },
+};
+
+type Mutation = [string, (value: typeof chart) => unknown];
+
+const invalid: Mutation[] = [
+ ["null", () => null],
+ ["an array", () => [chart]],
+ ["no title", ({ title: _, ...rest }) => rest],
+ ["a numeric query", (c) => ({ ...c, query: 1 })],
+ ["an undefined groupBy", (c) => ({ ...c, groupBy: undefined })],
+ ["no timeRange", (c) => ({ ...c, timeRange: null })],
+ ["a series object", (c) => ({ ...c, series: {} })],
+ [
+ "a string bucket value",
+ (c) => ({
+ ...c,
+ series: [
+ {
+ ...c.series[0],
+ buckets: [{ ...c.series[0]?.buckets[0], value: "12" }],
+ },
+ ],
+ }),
+ ],
+ [
+ "a bucket without incomplete",
+ (c) => ({
+ ...c,
+ series: [{ ...c.series[0], buckets: [{ time: "t", value: 1 }] }],
+ }),
+ ],
+ ["a peak without time", (c) => ({ ...c, peak: { series: "a", value: 1 } })],
+ ["no ingestion", ({ ingestion: _, ...rest }) => rest],
+ [
+ "a string delaySeconds",
+ (c) => ({ ...c, ingestion: { ...c.ingestion, delaySeconds: "5" } }),
+ ],
+];
+
+describe("parseChartResult", () => {
+ it("returns what renderSentryChartOutputSchema returns for a valid result", () => {
+ const input = { ...chart, extra: "dropped", peak: { ...chart.peak } };
+
+ expect(parseChartResult(input)).toEqual(
+ renderSentryChartOutputSchema.parse(input),
+ );
+ expect(parseChartResult(input)).not.toHaveProperty("extra");
+ });
+
+ it("accepts null peak and ingestion", () => {
+ expect(parseChartResult({ ...chart, peak: null, ingestion: null })).toEqual(
+ { ...chart, peak: null, ingestion: null },
+ );
+ });
+
+ it.each(invalid)("rejects %s, as the schema does", (_, mutate) => {
+ const input = mutate(structuredClone(chart));
+
+ expect(renderSentryChartOutputSchema.safeParse(input).success).toBe(false);
+ expect(parseChartResult(input)).toBeNull();
+ });
+});
diff --git a/packages/mcp-core/chart-app/parse.ts b/packages/mcp-core/chart-app/parse.ts
new file mode 100644
index 0000000000..6867e2bc16
--- /dev/null
+++ b/packages/mcp-core/chart-app/parse.ts
@@ -0,0 +1,110 @@
+/**
+ * Parses an untrusted render_sentry_chart `structuredContent` into a
+ * ChartResult, or returns null. Hand-written so the view ships without zod;
+ * parse.test.ts keeps it in step with renderSentryChartOutputSchema. Builds a
+ * new object, so unknown fields never reach the view.
+ */
+import type { ChartResult } from "../src/tools/support/chart/schema";
+
+type Series = ChartResult["series"][number];
+type Bucket = Series["buckets"][number];
+
+/** Thrown inside the parser; parseChartResult turns it into null. */
+class Invalid extends Error {}
+
+function record(value: unknown): Record {
+ if (typeof value !== "object" || value === null || Array.isArray(value)) {
+ throw new Invalid();
+ }
+ return value as Record;
+}
+
+function str(value: unknown): string {
+ if (typeof value !== "string") throw new Invalid();
+ return value;
+}
+
+function num(value: unknown): number {
+ if (typeof value !== "number" || !Number.isFinite(value)) throw new Invalid();
+ return value;
+}
+
+function bool(value: unknown): boolean {
+ if (typeof value !== "boolean") throw new Invalid();
+ return value;
+}
+
+function nullable(parse: (value: unknown) => T, value: unknown): T | null {
+ return value === null ? null : parse(value);
+}
+
+function list(parse: (value: unknown) => T, value: unknown): T[] {
+ if (!Array.isArray(value)) throw new Invalid();
+ return value.map(parse);
+}
+
+function bucket(value: unknown): Bucket {
+ const b = record(value);
+ return {
+ time: str(b["time"]),
+ value: num(b["value"]),
+ incomplete: bool(b["incomplete"]),
+ outsideRetention: bool(b["outsideRetention"]),
+ };
+}
+
+function series(value: unknown): Series {
+ const s = record(value);
+ return {
+ label: str(s["label"]),
+ total: nullable(num, s["total"]),
+ buckets: list(bucket, s["buckets"]),
+ };
+}
+
+function peak(value: unknown): NonNullable {
+ const p = record(value);
+ return {
+ series: str(p["series"]),
+ time: str(p["time"]),
+ value: num(p["value"]),
+ };
+}
+
+function ingestion(value: unknown): NonNullable {
+ const i = record(value);
+ return {
+ status: str(i["status"]),
+ delaySeconds: nullable(num, i["delaySeconds"]),
+ completeThrough: nullable(str, i["completeThrough"]),
+ };
+}
+
+export function parseChartResult(value: unknown): ChartResult | null {
+ try {
+ const c = record(value);
+ const range = record(c["timeRange"]);
+ return {
+ title: str(c["title"]),
+ dataset: str(c["dataset"]),
+ query: str(c["query"]),
+ yAxis: str(c["yAxis"]),
+ groupBy: nullable(str, c["groupBy"]),
+ valueType: nullable(str, c["valueType"]),
+ valueUnit: nullable(str, c["valueUnit"]),
+ interval: str(c["interval"]),
+ timeRange: {
+ statsPeriod: nullable(str, range["statsPeriod"]),
+ start: nullable(str, range["start"]),
+ end: nullable(str, range["end"]),
+ },
+ url: str(c["url"]),
+ series: list(series, c["series"]),
+ peak: nullable(peak, c["peak"]),
+ ingestion: nullable(ingestion, c["ingestion"]),
+ };
+ } catch (error) {
+ if (error instanceof Invalid) return null;
+ throw error;
+ }
+}
diff --git a/packages/mcp-core/chart-app/styles.css b/packages/mcp-core/chart-app/styles.css
new file mode 100644
index 0000000000..be9ca23e37
--- /dev/null
+++ b/packages/mcp-core/chart-app/styles.css
@@ -0,0 +1,241 @@
+:root {
+ color-scheme: light;
+ --bg: var(--color-background-primary, #ffffff);
+ --panel: var(--color-background-secondary, #faf9fb);
+ --fg: var(--color-text-primary, #2b2233);
+ --muted: var(--color-text-secondary, #71637e);
+ --border: var(--color-border-primary, #e0dce5);
+ --grid: var(--color-border-tertiary, #f0ecf3);
+ --danger: var(--color-text-danger, #cf2126);
+ --accent: #6c5fc7;
+ --radius: var(--border-radius-md, 6px);
+ font-family: var(
+ --font-sans,
+ -apple-system,
+ BlinkMacSystemFont,
+ "Segoe UI",
+ Roboto,
+ sans-serif
+ );
+ font-size: var(--font-text-sm-size, 13px);
+}
+
+[data-theme="dark"] {
+ color-scheme: dark;
+ --bg: var(--color-background-primary, #1e1a25);
+ --panel: var(--color-background-secondary, #262130);
+ --fg: var(--color-text-primary, #ebe6ef);
+ --muted: var(--color-text-secondary, #a397b0);
+ --border: var(--color-border-primary, #3e3446);
+ --grid: var(--color-border-tertiary, #2f2838);
+ --danger: var(--color-text-danger, #ff7f7f);
+ --accent: #a796f0;
+}
+
+* {
+ box-sizing: border-box;
+}
+
+html,
+body {
+ margin: 0;
+ background: var(--bg);
+ color: var(--fg);
+}
+
+main {
+ padding: 14px 16px 12px;
+}
+
+header {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: 8px 16px;
+}
+
+h1 {
+ margin: 0;
+ font-size: var(--font-heading-sm-size, 15px);
+ font-weight: var(--font-weight-semibold, 600);
+ overflow-wrap: anywhere;
+}
+
+.subtitle {
+ margin-top: 2px;
+ color: var(--muted);
+ overflow-wrap: anywhere;
+}
+
+.subtitle code {
+ font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+ font-size: 0.95em;
+}
+
+.controls {
+ display: flex;
+ gap: 8px;
+ align-items: center;
+}
+
+.ranges {
+ display: inline-flex;
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ overflow: hidden;
+}
+
+button {
+ font: inherit;
+ color: var(--fg);
+ background: var(--bg);
+ border: 0;
+ padding: 4px 10px;
+ cursor: pointer;
+}
+
+.ranges button + button {
+ border-left: 1px solid var(--border);
+}
+
+.ranges button[aria-pressed="true"] {
+ background: var(--accent);
+ color: #ffffff;
+}
+
+button:disabled {
+ cursor: default;
+ opacity: 0.6;
+}
+
+.open {
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+}
+
+.stats {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 4px 16px;
+ margin: 10px 0 4px;
+ color: var(--muted);
+}
+
+.stats strong {
+ color: var(--fg);
+ font-weight: var(--font-weight-semibold, 600);
+}
+
+.chart {
+ position: relative;
+ transition: opacity 120ms;
+}
+
+.chart[data-loading="true"] {
+ opacity: 0.45;
+}
+
+svg {
+ display: block;
+ width: 100%;
+ overflow: visible;
+}
+
+.axis text {
+ fill: var(--muted);
+ font-size: 11px;
+}
+
+.grid line {
+ stroke: var(--grid);
+}
+
+.baseline {
+ stroke: var(--border);
+}
+
+.incomplete-band {
+ fill: url(#incomplete-hatch);
+}
+
+#incomplete-hatch line {
+ stroke: var(--border);
+}
+
+.crosshair {
+ stroke: var(--muted);
+ stroke-dasharray: 2 3;
+}
+
+.tooltip {
+ position: absolute;
+ pointer-events: none;
+ min-width: 140px;
+ padding: 6px 8px;
+ background: var(--panel);
+ border: 1px solid var(--border);
+ border-radius: var(--radius);
+ box-shadow: var(--shadow-md, 0 2px 8px rgba(0, 0, 0, 0.15));
+ font-size: 12px;
+}
+
+.tooltip .time {
+ color: var(--muted);
+ margin-bottom: 4px;
+}
+
+.tooltip .row,
+.legend .item {
+ display: flex;
+ gap: 6px;
+ align-items: center;
+}
+
+.tooltip .row span:last-child {
+ margin-left: auto;
+ padding-left: 12px;
+ font-variant-numeric: tabular-nums;
+}
+
+.swatch {
+ width: 8px;
+ height: 8px;
+ border-radius: 2px;
+ flex: none;
+}
+
+.legend {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 4px 14px;
+ margin-top: 6px;
+ color: var(--muted);
+}
+
+.note {
+ margin-top: 6px;
+ color: var(--muted);
+ font-size: 12px;
+}
+
+.state {
+ display: grid;
+ place-items: center;
+ min-height: 160px;
+ color: var(--muted);
+ text-align: center;
+ border: 1px dashed var(--border);
+ border-radius: var(--radius);
+ margin-top: 10px;
+ padding: 16px;
+}
+
+.state.error {
+ color: var(--danger);
+}
+
+/* Author display rules otherwise beat the hidden attribute. */
+[hidden] {
+ display: none !important;
+}
diff --git a/packages/mcp-core/chart-app/tsconfig.json b/packages/mcp-core/chart-app/tsconfig.json
new file mode 100644
index 0000000000..ec11a7673a
--- /dev/null
+++ b/packages/mcp-core/chart-app/tsconfig.json
@@ -0,0 +1,10 @@
+{
+ "extends": "../../../tsconfig.base.json",
+ "compilerOptions": {
+ // Runs in an MCP Apps host's sandboxed iframe, not in Node.
+ "lib": ["ES2023", "DOM", "DOM.Iterable"],
+ "types": [],
+ "noEmit": true
+ },
+ "include": ["*.ts"]
+}
diff --git a/packages/mcp-core/package.json b/packages/mcp-core/package.json
index ea61352bd0..a157bd9a71 100644
--- a/packages/mcp-core/package.json
+++ b/packages/mcp-core/package.json
@@ -154,19 +154,27 @@
"test": "pnpm run validate-skills && vitest run",
"test:ci": "pnpm run generate-definitions && pnpm run validate-skills && vitest run --reporter=default --reporter=junit --outputFile=tests.junit.xml",
"test:watch": "pnpm run generate-definitions && vitest",
- "typecheck": "tsc --noEmit && tsc --noEmit -p scripts/tsconfig.json",
+ "typecheck": "tsc --noEmit && tsc --noEmit -p scripts/tsconfig.json && tsc --noEmit -p chart-app",
"generate-definitions": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-definitions.ts && oxfmt --write src/toolDefinitions.json src/skillDefinitions.json",
+ "generate-chart-app": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-chart-app.ts",
+ "ci:policy": "pnpm run generate-chart-app --check",
"generate-platform-setup": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-platform-setup.ts && oxfmt --write src/tools/support/project-setup/platforms.json",
"generate-otel-namespaces": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-otel-namespaces.ts",
+ "measure-ui": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/measure-ui-views.ts",
"measure-tokens": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/measure-token-cost.ts",
"validate-skills": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/validate-skills-mapping.ts"
},
"devDependencies": {
"@ai-sdk/provider": "^3.0.6",
"@ai-sdk/provider-utils": "^4.0.11",
+ "@modelcontextprotocol/client": "catalog:",
+ "@modelcontextprotocol/core": "catalog:",
+ "@modelcontextprotocol/ext-apps": "catalog:",
"@modelcontextprotocol/sdk": "catalog:",
"@sentry/mcp-server-mocks": "workspace:*",
+ "esbuild": "^0.28.1",
"msw": "catalog:",
+ "playwright-core": "catalog:",
"tiktoken": "^1.0.18",
"yaml": "^2.8.3"
},
diff --git a/packages/mcp-core/scripts/generate-chart-app.ts b/packages/mcp-core/scripts/generate-chart-app.ts
new file mode 100644
index 0000000000..5f26b7d9f5
--- /dev/null
+++ b/packages/mcp-core/scripts/generate-chart-app.ts
@@ -0,0 +1,75 @@
+/**
+ * Bundles the render_sentry_chart view (chart-app/) into one self-contained
+ * HTML document and writes it to src/ui/chart-app.generated.ts, so the stdio
+ * server and the Cloudflare Worker serve it without reading files.
+ *
+ * `--check` fails instead of writing when the committed file is stale. Both
+ * modes fail when the view breaks a rule in view-policy.ts.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { build, transform } from "esbuild";
+import { CHART_UI_RESOURCE } from "../src/ui-resources.ts";
+import { viewHtmlProblems } from "./view-policy.ts";
+
+const BUDGET_BYTES = CHART_UI_RESOURCE.budgetBytes;
+
+const appDir = fileURLToPath(new URL("../chart-app/", import.meta.url));
+const outFile = fileURLToPath(
+ new URL("../src/ui/chart-app.generated.ts", import.meta.url),
+);
+
+const bundle = await build({
+ entryPoints: [`${appDir}main.ts`],
+ bundle: true,
+ minify: true,
+ format: "iife",
+ platform: "browser",
+ target: "es2022",
+ legalComments: "none",
+ charset: "utf8",
+ write: false,
+});
+const script = bundle.outputFiles[0]?.text;
+if (!script) {
+ throw new Error("esbuild produced no output for chart-app/main.ts");
+}
+const style = await transform(readFileSync(`${appDir}styles.css`, "utf8"), {
+ loader: "css",
+ minify: true,
+});
+
+const html = [
+ "",
+ '',
+ '',
+ "Sentry chart",
+ ``,
+ // An inline script ends at the first ``,
+].join("");
+
+const problems = viewHtmlProblems("The chart view", html, BUDGET_BYTES);
+if (problems.length > 0) {
+ console.error(problems.join("\n"));
+ process.exit(1);
+}
+
+const source = `// Generated by scripts/generate-chart-app.ts from chart-app/. Do not edit.
+export const CHART_APP_HTML = ${JSON.stringify(html)};
+`;
+
+if (process.argv.includes("--check")) {
+ if (readFileSync(outFile, "utf8") !== source) {
+ console.error(
+ "src/ui/chart-app.generated.ts is stale. Run: pnpm --filter @sentry/mcp-core generate-chart-app",
+ );
+ process.exit(1);
+ }
+ console.log("src/ui/chart-app.generated.ts is up to date.");
+} else {
+ writeFileSync(outFile, source);
+ console.log(
+ `Wrote src/ui/chart-app.generated.ts (${Buffer.byteLength(html)} of ${BUDGET_BYTES} bytes).`,
+ );
+}
diff --git a/packages/mcp-core/scripts/measure-ui-views.ts b/packages/mcp-core/scripts/measure-ui-views.ts
new file mode 100644
index 0000000000..d074464fb9
--- /dev/null
+++ b/packages/mcp-core/scripts/measure-ui-views.ts
@@ -0,0 +1,191 @@
+/**
+ * Measure the MCP Apps views that hosts download.
+ *
+ * Builds the server with every skill, lists its resources, and reads each
+ * `ui://` resource through `resources/read`, as a host does before it renders
+ * a view. Reports raw, gzip, and brotli bytes against the view's budget.
+ *
+ * Usage:
+ * pnpm run measure-ui # Display table
+ * pnpm run measure-ui -- -o ui-stats.json # Write JSON to file
+ * pnpm run measure-ui -- --markdown report.md # Append a report section
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { brotliCompressSync, constants, gzipSync } from "node:zlib";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { buildServer } from "../src/server.ts";
+import { ALL_SKILLS } from "../src/skills.ts";
+import { UI_RESOURCES } from "../src/ui-resources.ts";
+
+interface ViewStats {
+ uri: string;
+ mime_type: string;
+ raw_bytes: number;
+ gzip_bytes: number;
+ brotli_bytes: number;
+ budget_bytes: number;
+ budget_percentage: number;
+}
+
+function parseArgs() {
+ const args = process.argv.slice(2);
+ let outputFile: string | null = null;
+ const markdownFiles: string[] = [];
+
+ for (let i = 0; i < args.length; i++) {
+ const arg = args[i];
+ if (arg === "--output" || arg === "-o" || arg === "--markdown") {
+ const file = args[i + 1];
+ if (!file) {
+ throw new Error(`${arg} requires a file path`);
+ }
+ if (arg === "--markdown") {
+ markdownFiles.push(file);
+ } else {
+ outputFile = file;
+ }
+ i++;
+ } else if (arg === "--help" || arg === "-h") {
+ console.log(`
+Usage: pnpm run measure-ui -- [options]
+
+Options:
+ -o, --output Write JSON output to file
+ --markdown Append the markdown report section to file (repeatable)
+ -h, --help Show this help message
+`);
+ process.exit(0);
+ }
+ }
+
+ return { outputFile, markdownFiles };
+}
+
+/** Reads every `ui://` resource the server lists, as a host would. */
+async function readViews(): Promise {
+ const server = buildServer({
+ context: {
+ accessToken: "measure-ui",
+ grantedSkills: new Set(ALL_SKILLS),
+ constraints: { organizationSlug: null, projectSlug: null },
+ sentryHost: "sentry.io",
+ },
+ // MCP Apps views ship to experimental sessions only for now.
+ experimentalMode: true,
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ const client = new Client({ name: "measure-ui", version: "1.0.0" });
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+
+ try {
+ const { resources } = await client.listResources();
+ const views: ViewStats[] = [];
+ for (const { uri } of resources.filter((r) => r.uri.startsWith("ui://"))) {
+ const budget = UI_RESOURCES.find((r) => r.uri === uri)?.budgetBytes;
+ if (budget === undefined) {
+ throw new Error(`${uri} is not in UI_RESOURCES, so it has no budget`);
+ }
+ const { contents } = await client.readResource({ uri });
+ for (const content of contents) {
+ const body =
+ "text" in content
+ ? Buffer.from(content.text, "utf8")
+ : Buffer.from(content.blob, "base64");
+ views.push({
+ uri: content.uri,
+ mime_type: content.mimeType ?? "",
+ raw_bytes: body.length,
+ gzip_bytes: gzipSync(body, { level: 9 }).length,
+ brotli_bytes: brotliCompressSync(body, {
+ params: { [constants.BROTLI_PARAM_QUALITY]: 11 },
+ }).length,
+ budget_bytes: budget,
+ budget_percentage: Number(((body.length / budget) * 100).toFixed(1)),
+ });
+ }
+ }
+ return views;
+ } finally {
+ await client.close();
+ await server.close();
+ }
+}
+
+const bytes = (n: number) => `${n.toLocaleString("en-US")} B`;
+
+function formatMarkdown(views: ViewStats[]): string {
+ const lines = [
+ "",
+ "### MCP Apps views",
+ "",
+ "Each `ui://` view as a host receives it from `resources/read`.",
+ "",
+ ];
+ if (views.length === 0) {
+ lines.push("_The server lists no `ui://` resources._");
+ } else {
+ lines.push(
+ "| View | MIME type | Raw | Gzip | Brotli | Budget | % of budget |",
+ "|------|-----------|-----|------|--------|--------|-------------|",
+ );
+ for (const view of views) {
+ lines.push(
+ `| \`${view.uri}\` | \`${view.mime_type}\` | ${bytes(view.raw_bytes)} | ${bytes(view.gzip_bytes)} | ${bytes(view.brotli_bytes)} | ${bytes(view.budget_bytes)} | ${view.budget_percentage}% |`,
+ );
+ }
+ lines.push(
+ "",
+ "The budget applies to raw bytes, and the view's generator fails over it.",
+ );
+ }
+ return `${lines.join("\n")}\n`;
+}
+
+function formatTable(views: ViewStats[]): string {
+ const lines = ["\n🧩 MCP Apps Views\n", "━".repeat(60)];
+ for (const view of views) {
+ lines.push(
+ view.uri,
+ ` MIME type: ${view.mime_type}`,
+ ` Raw: ${bytes(view.raw_bytes)} (${view.budget_percentage}% of ${bytes(view.budget_bytes)})`,
+ ` Gzip: ${bytes(view.gzip_bytes)}`,
+ ` Brotli: ${bytes(view.brotli_bytes)}`,
+ );
+ }
+ if (views.length === 0) {
+ lines.push("The server lists no ui:// resources.");
+ }
+ return lines.join("\n");
+}
+
+async function main() {
+ try {
+ const { outputFile, markdownFiles } = parseArgs();
+ const views = await readViews();
+
+ for (const file of markdownFiles) {
+ fs.appendFileSync(file, formatMarkdown(views));
+ }
+ if (outputFile) {
+ const absolutePath = path.resolve(outputFile);
+ fs.writeFileSync(
+ absolutePath,
+ JSON.stringify({ view_count: views.length, views }, null, 2),
+ );
+ console.log(`✅ UI view stats written to: ${absolutePath}`);
+ }
+ console.log(formatTable(views));
+ } catch (error) {
+ const err = error as Error;
+ console.error("[ERROR]", err.message, err.stack);
+ process.exit(1);
+ }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+ void main();
+}
diff --git a/packages/mcp-core/scripts/view-policy.test.ts b/packages/mcp-core/scripts/view-policy.test.ts
new file mode 100644
index 0000000000..9b829eb371
--- /dev/null
+++ b/packages/mcp-core/scripts/view-policy.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { CHART_APP_HTML } from "../src/ui/chart-app.generated.ts";
+import { CHART_UI_RESOURCE } from "../src/ui-resources.ts";
+import { viewHtmlProblems } from "./view-policy.ts";
+
+const page = (body: string) =>
+ `${body}`;
+
+describe("viewHtmlProblems", () => {
+ it("passes the generated chart view", () => {
+ expect(
+ viewHtmlProblems("chart", CHART_APP_HTML, CHART_UI_RESOURCE.budgetBytes),
+ ).toEqual([]);
+ });
+
+ it("fails a view over its budget", () => {
+ expect(viewHtmlProblems("big", page("x".repeat(2048)), 1024)).toEqual([
+ expect.stringContaining("over its 1024-byte budget"),
+ ]);
+ });
+
+ it.each([
+ ['', "src or href"],
+ ['', "src or href"],
+ ['', ""],
+ ["", "@import"],
+ ["", "url()"],
+ ["", "fetch()"],
+ ["", "XMLHttpRequest"],
+ ["", "WebSocket"],
+ ["", "EventSource"],
+ ["", "sendBeacon"],
+ ["", "dynamic import()"],
+ ])("fails a view that loads from the network: %s", (body, label) => {
+ expect(viewHtmlProblems("leaky", page(body), 1024)).toEqual([
+ expect.stringContaining(label),
+ ]);
+ });
+
+ it("allows inline data and the SVG namespace", () => {
+ const body =
+ '';
+ expect(viewHtmlProblems("inline", page(body), 1024)).toEqual([]);
+ });
+});
diff --git a/packages/mcp-core/scripts/view-policy.ts b/packages/mcp-core/scripts/view-policy.ts
new file mode 100644
index 0000000000..be20b66fae
--- /dev/null
+++ b/packages/mcp-core/scripts/view-policy.ts
@@ -0,0 +1,43 @@
+/**
+ * Checks a generated MCP Apps view before it is written or accepted as up to
+ * date: it fits its byte budget and loads nothing from the network, so it
+ * runs under the spec's default CSP with an empty `csp`. See
+ * design/mcp-apps.md.
+ */
+
+/** Network loads that an empty `csp` would block, so a view must not use them. */
+const NETWORK_PATTERNS: ReadonlyArray<[string, RegExp]> = [
+ ["an external src or href", /\b(?:src|href)\s*=\s*["']?(?:https?:)?\/\//i],
+ ["a element", / budgetBytes) {
+ problems.push(
+ `${name} is ${bytes} bytes, over its ${budgetBytes}-byte budget. Drop a dependency or raise the budget on purpose.`,
+ );
+ }
+ for (const [label, pattern] of NETWORK_PATTERNS) {
+ if (pattern.test(html)) {
+ problems.push(
+ `${name} uses ${label}. A view loads nothing from the network.`,
+ );
+ }
+ }
+ return problems;
+}
diff --git a/packages/mcp-core/src/api-client/client.ts b/packages/mcp-core/src/api-client/client.ts
index 1b2d5f3dc3..7f848ce725 100644
--- a/packages/mcp-core/src/api-client/client.ts
+++ b/packages/mcp-core/src/api-client/client.ts
@@ -4747,6 +4747,7 @@ export class SentryApiService {
statsPeriod,
start,
end,
+ topEvents,
}: {
organizationSlug: string;
query: string;
@@ -4757,6 +4758,11 @@ export class SentryApiService {
statsPeriod?: string;
start?: string;
end?: string;
+ /**
+ * One series per value of `groupBy`, for the `limit` values with the
+ * highest `yAxis`, without an "Other" series.
+ */
+ topEvents?: { groupBy: string; limit: number } | undefined;
},
opts?: RequestOptions,
) {
@@ -4764,6 +4770,12 @@ export class SentryApiService {
queryParams.set("dataset", normalizeEventsDataset(dataset));
queryParams.set("query", query);
queryParams.set("yAxis", yAxis);
+ if (topEvents) {
+ queryParams.set("topEvents", String(topEvents.limit));
+ queryParams.set("groupBy", topEvents.groupBy);
+ queryParams.set("sort", `-${yAxis}`);
+ queryParams.set("excludeOther", "1");
+ }
// Omit interval to let Sentry pick a sensible bucket size for the range.
if (interval) {
queryParams.set("interval", interval);
diff --git a/packages/mcp-core/src/api-client/schema.ts b/packages/mcp-core/src/api-client/schema.ts
index 79b4a826f5..00321a0750 100644
--- a/packages/mcp-core/src/api-client/schema.ts
+++ b/packages/mcp-core/src/api-client/schema.ts
@@ -2668,7 +2668,8 @@ export const EventsTimeSeriesValueSchema = z
/**
* Response from the events-timeseries endpoint. The MCP always requests a
- * single yAxis without topEvents, so `timeSeries` holds exactly one series.
+ * single yAxis, so `timeSeries` holds one series, or one per group with
+ * `topEvents`, each naming its group in `groupBy`.
*/
export const EventsTimeSeriesResponseSchema = z
.object({
@@ -2677,6 +2678,14 @@ export const EventsTimeSeriesResponseSchema = z
.object({
yAxis: z.string(),
values: z.array(EventsTimeSeriesValueSchema),
+ groupBy: z
+ .array(
+ z.object({
+ key: z.string(),
+ value: z.union([z.string(), z.number()]).nullable(),
+ }),
+ )
+ .optional(),
meta: z
.object({
// Bucket width in milliseconds
diff --git a/packages/mcp-core/src/server.metadata.test.ts b/packages/mcp-core/src/server.metadata.test.ts
index b6ad31bb02..04fe4b834b 100644
--- a/packages/mcp-core/src/server.metadata.test.ts
+++ b/packages/mcp-core/src/server.metadata.test.ts
@@ -34,6 +34,9 @@ const ALLOWED_TOOL_META: Record = {
// Claude Code keeps it loaded so a pasted Sentry URL works without a tool
// search. See docs/mcp/harnesses.md.
get_sentry_resource: ["anthropic/alwaysLoad"],
+ // MCP Apps hosts (Claude, VS Code) read `ui`; ChatGPT reads
+ // `openai/outputTemplate`. See src/ui-resources.ts.
+ render_sentry_chart: ["ui", "openai/outputTemplate"],
};
/** Tools that return no `structuredContent` by design. */
diff --git a/packages/mcp-core/src/server.ts b/packages/mcp-core/src/server.ts
index 4d56161486..49702c0b8f 100644
--- a/packages/mcp-core/src/server.ts
+++ b/packages/mcp-core/src/server.ts
@@ -59,6 +59,7 @@ import tools from "./tools/index";
import { isCatalogInfrastructureToolName } from "./tools/surfaces";
import type { StructuredToolOutput } from "./tools/types";
import type { ServerContext } from "./types";
+import { registerUiResources } from "./ui-resources";
import { getServerVersion } from "./version";
function getSkillGrantedAttributeName(skill: Skill): string {
@@ -340,6 +341,10 @@ export function buildServer({
for (const { name, config, handler } of registrations) {
server.registerTool(name, config, handler);
}
+ registerUiResources(
+ server,
+ registrations.map(({ config }) => config),
+ );
// Registration enables this by default, but each server's tool catalog is fixed.
if (registrations.length > 0) {
server.server.registerCapabilities({ tools: { listChanged: false } });
@@ -409,6 +414,7 @@ function configureServer({
tool.outputSchema ??
(experimentalMode ? tool.experimentalOutputSchema : undefined),
annotations: tool.annotations,
+ ...(tool._meta && { _meta: tool._meta }),
};
const handleToolCall = async (
params: unknown,
diff --git a/packages/mcp-core/src/server.ui-resources.test.ts b/packages/mcp-core/src/server.ui-resources.test.ts
new file mode 100644
index 0000000000..6f118a8036
--- /dev/null
+++ b/packages/mcp-core/src/server.ui-resources.test.ts
@@ -0,0 +1,95 @@
+/**
+ * MCP Apps: what a host reads to render render_sentry_chart inline. The tool
+ * names its view in `_meta.ui.resourceUri`, and that `ui://` resource reads
+ * back as a self-contained HTML document with the MCP Apps mime type. MCP
+ * Apps ship to experimental sessions only for now.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { describe, expect, it, vi } from "vitest";
+import { buildServer } from "./server";
+import type { Skill } from "./skills";
+import type { ServerContext } from "./types";
+
+vi.mock("@sentry/core/server", () => ({
+ wrapMcpServerWithSentry: vi.fn((server) => server),
+}));
+
+const CHART_URI = "ui://sentry/chart/v1.html";
+const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+
+async function connect(skills: Skill[], experimentalMode = true) {
+ const context: ServerContext = {
+ accessToken: "test-token",
+ grantedSkills: new Set(skills),
+ constraints: { organizationSlug: null, projectSlug: null },
+ sentryHost: "sentry.io",
+ };
+ const server = buildServer({ context, experimentalMode });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ const client = new Client({ name: "mcp-apps-host", version: "1.0.0" });
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+ return {
+ client,
+ async [Symbol.asyncDispose]() {
+ await client.close();
+ await server.close();
+ },
+ };
+}
+
+describe("MCP Apps chart view", () => {
+ it("links render_sentry_chart to its view in tools/list", async () => {
+ await using session = await connect(["inspect"]);
+ const { tools } = await session.client.listTools();
+ const chartTool = tools.find((tool) => tool.name === "render_sentry_chart");
+
+ expect(chartTool?._meta).toEqual({
+ ui: { resourceUri: CHART_URI },
+ "openai/outputTemplate": CHART_URI,
+ });
+ });
+
+ it("lists and reads the view as a self-contained HTML document", async () => {
+ await using session = await connect(["inspect"]);
+
+ expect(session.client.getServerCapabilities()?.resources).toEqual({
+ listChanged: false,
+ });
+ const { resources } = await session.client.listResources();
+ expect(resources).toEqual([
+ expect.objectContaining({ uri: CHART_URI, mimeType: MCP_APP_MIME_TYPE }),
+ ]);
+
+ const { contents } = await session.client.readResource({ uri: CHART_URI });
+ expect(contents).toHaveLength(1);
+ const [view] = contents;
+ expect(view).toMatchObject({
+ uri: CHART_URI,
+ mimeType: MCP_APP_MIME_TYPE,
+ _meta: { ui: { csp: {}, prefersBorder: true } },
+ });
+ const html = view && "text" in view ? view.text : "";
+ expect(html.startsWith("")).toBe(true);
+ expect(html.endsWith("")).toBe(true);
+ });
+
+ it("lists no view when the session cannot call the chart tool", async () => {
+ await using session = await connect(["project-management"]);
+ const { tools } = await session.client.listTools();
+
+ expect(tools.map((tool) => tool.name)).not.toContain("render_sentry_chart");
+ expect(session.client.getServerCapabilities()?.resources).toBeUndefined();
+ });
+
+ it("keeps the chart tool and its view out of stable sessions", async () => {
+ await using session = await connect(["inspect"], false);
+ const { tools } = await session.client.listTools();
+
+ expect(tools.map((tool) => tool.name)).not.toContain("render_sentry_chart");
+ expect(tools.some((tool) => tool._meta?.["ui"] !== undefined)).toBe(false);
+ expect(session.client.getServerCapabilities()?.resources).toBeUndefined();
+ });
+});
diff --git a/packages/mcp-core/src/test-utils/ui-resource-policy.ts b/packages/mcp-core/src/test-utils/ui-resource-policy.ts
new file mode 100644
index 0000000000..69ac575f68
--- /dev/null
+++ b/packages/mcp-core/src/test-utils/ui-resource-policy.ts
@@ -0,0 +1,70 @@
+/**
+ * The MCP Apps rules from design/mcp-apps.md that hold between tools and
+ * views: every `_meta.ui.resourceUri` names a known view, every view has a
+ * tool, a view's `ui://` URI is versioned and changes with its HTML, and its
+ * `csp` allows no origins.
+ */
+import { createHash } from "node:crypto";
+import type { UiResource } from "../ui-resources";
+
+interface ToolWithMeta {
+ name: string;
+ _meta?: Record | undefined;
+}
+
+function resourceUri(tool: ToolWithMeta): unknown {
+ const ui = tool._meta?.["ui"];
+ return typeof ui === "object" && ui !== null && "resourceUri" in ui
+ ? ui.resourceUri
+ : undefined;
+}
+
+/** Returns one message per broken rule; empty when every rule holds. */
+export async function uiResourceProblems(
+ tools: readonly ToolWithMeta[],
+ resources: readonly UiResource[],
+): Promise {
+ const problems: string[] = [];
+ const uris = new Set(resources.map((resource) => resource.uri));
+ const referenced = new Set();
+ for (const tool of tools) {
+ const uri = resourceUri(tool);
+ if (uri === undefined) continue;
+ referenced.add(uri);
+ if (typeof uri !== "string" || !uris.has(uri)) {
+ problems.push(
+ `${tool.name} names view ${JSON.stringify(uri)}, which is not a UI resource.`,
+ );
+ }
+ }
+ if (uris.size !== resources.length) {
+ problems.push("Two UI resources share a URI.");
+ }
+ for (const resource of resources) {
+ if (!referenced.has(resource.uri)) {
+ problems.push(`No tool names ${resource.uri}, so it is never listed.`);
+ }
+ if (!/^ui:\/\/[^/]+\/.*v\d+/.test(resource.uri)) {
+ problems.push(
+ `${resource.uri} has no version. Hosts cache views by URI, so it needs one, such as v1.`,
+ );
+ }
+ const domains = Object.entries(resource.meta.csp).filter(
+ ([, list]) => list.length > 0,
+ );
+ if (domains.length > 0) {
+ problems.push(
+ `${resource.uri} allows ${domains.map(([key]) => key).join(", ")} in its csp. A view loads nothing from the network.`,
+ );
+ }
+ const sha256 = createHash("sha256")
+ .update(await resource.loadHtml())
+ .digest("hex");
+ if (sha256 !== resource.htmlSha256) {
+ problems.push(
+ `The HTML of ${resource.uri} changed. Hosts cache views by URI, so bump its version and set htmlSha256 to "${sha256}".`,
+ );
+ }
+ }
+ return problems;
+}
diff --git a/packages/mcp-core/src/tools/catalog/index.ts b/packages/mcp-core/src/tools/catalog/index.ts
index d2a897479b..155fab4b4e 100644
--- a/packages/mcp-core/src/tools/catalog/index.ts
+++ b/packages/mcp-core/src/tools/catalog/index.ts
@@ -42,6 +42,7 @@ import linkIssue from "./link-issue";
import unlinkIssue from "./unlink-issue";
import searchEvents from "./search-events";
import searchErrors from "./search-errors";
+import renderSentryChart from "./render-sentry-chart";
import searchLogs from "./search-logs";
import searchTraces from "./search-traces";
import searchMetrics from "./search-metrics";
@@ -176,6 +177,7 @@ const catalogTools = withFreshReadInputs({
search_profiles: searchProfiles,
search_replays: searchReplays,
search_events: searchEvents,
+ render_sentry_chart: renderSentryChart,
create_team: createTeam,
create_project: createProject,
update_project: updateProject,
diff --git a/packages/mcp-core/src/tools/catalog/render-sentry-chart.test.ts b/packages/mcp-core/src/tools/catalog/render-sentry-chart.test.ts
new file mode 100644
index 0000000000..de05aab3d1
--- /dev/null
+++ b/packages/mcp-core/src/tools/catalog/render-sentry-chart.test.ts
@@ -0,0 +1,255 @@
+import { mswServer } from "@sentry/mcp-server-mocks";
+import { HttpResponse, http } from "msw";
+import { describe, expect, it } from "vitest";
+import { UserInputError } from "../../errors";
+import {
+ assertStructuredOnlyResult,
+ getStructuredContent,
+} from "../../test-utils/structured-content.js";
+import type { ChartResult } from "../support/chart/schema";
+import renderSentryChart from "./render-sentry-chart.js";
+
+const context = {
+ constraints: { organizationSlug: null },
+ accessToken: "access-token",
+ userId: "1",
+};
+
+const TIMESERIES_URL =
+ "https://sentry.io/api/0/organizations/sentry-mcp-evals/events-timeseries/";
+
+const baseParams = {
+ organizationSlug: "sentry-mcp-evals",
+ regionUrl: null,
+ dataset: "errors" as const,
+ query: "level:error",
+ yAxis: "count()",
+ groupBy: null,
+ projectSlug: null,
+ period: "1h",
+ start: null,
+ end: null,
+ interval: "15m",
+ title: null,
+};
+
+describe("render_sentry_chart", () => {
+ it("returns every bucket of the series", async () => {
+ const result = await renderSentryChart.handler(baseParams, context);
+
+ assertStructuredOnlyResult(result);
+ expect(getStructuredContent(result)).toMatchInlineSnapshot(`
+ {
+ "dataset": "errors",
+ "groupBy": null,
+ "ingestion": null,
+ "interval": "15m",
+ "peak": {
+ "series": "count()",
+ "time": "2025-09-10T23:30:00.000Z",
+ "value": 140,
+ },
+ "query": "level:error",
+ "series": [
+ {
+ "buckets": [
+ {
+ "incomplete": false,
+ "outsideRetention": false,
+ "time": "2025-09-10T23:00:00.000Z",
+ "value": 56,
+ },
+ {
+ "incomplete": false,
+ "outsideRetention": false,
+ "time": "2025-09-10T23:15:00.000Z",
+ "value": 56,
+ },
+ {
+ "incomplete": false,
+ "outsideRetention": false,
+ "time": "2025-09-10T23:30:00.000Z",
+ "value": 140,
+ },
+ {
+ "incomplete": true,
+ "outsideRetention": false,
+ "time": "2025-09-10T23:45:00.000Z",
+ "value": 56,
+ },
+ ],
+ "label": "count()",
+ "total": 308,
+ },
+ ],
+ "timeRange": {
+ "end": null,
+ "start": null,
+ "statsPeriod": "1h",
+ },
+ "title": "count()",
+ "url": "https://sentry-mcp-evals.sentry.io/explore/discover/homepage/?dataset=errors&queryDataset=error-events&query=level%3Aerror&project=-1&field=count%28%29&sort=-count%28%29&statsPeriod=1h&mode=aggregate&yAxis=count%28%29",
+ "valueType": "integer",
+ "valueUnit": null,
+ "yAxis": "count()",
+ }
+ `);
+ });
+
+ it("asks Sentry for the top 5 groups and labels each series by its value", async () => {
+ let captured: URLSearchParams | undefined;
+ mswServer.use(
+ http.get(TIMESERIES_URL, ({ request }) => {
+ captured = new URL(request.url).searchParams;
+ return HttpResponse.json({
+ timeSeries: ["2.4.1", null].map((release, index) => ({
+ yAxis: "p95(span.duration)",
+ groupBy: [{ key: "release", value: release }],
+ values: [
+ {
+ timestamp: 1757545200000,
+ value: 120 - index,
+ incomplete: false,
+ },
+ ],
+ meta: {
+ interval: 3600000,
+ valueType: "duration",
+ valueUnit: "millisecond",
+ order: index,
+ isOther: false,
+ },
+ })),
+ });
+ }),
+ );
+
+ const result = await renderSentryChart.handler(
+ {
+ ...baseParams,
+ dataset: "spans",
+ yAxis: "p95(span.duration)",
+ groupBy: "release",
+ period: null,
+ interval: null,
+ },
+ context,
+ );
+
+ expect(Object.fromEntries(captured ?? [])).toMatchObject({
+ dataset: "spans",
+ yAxis: "p95(span.duration)",
+ topEvents: "5",
+ groupBy: "release",
+ sort: "-p95(span.duration)",
+ excludeOther: "1",
+ statsPeriod: "24h",
+ });
+ const chart = getStructuredContent(result);
+ expect(chart.title).toBe("p95(span.duration) by release");
+ expect(chart.valueUnit).toBe("millisecond");
+ expect(chart.series.map(({ label, total }) => ({ label, total }))).toEqual([
+ { label: "2.4.1", total: null },
+ { label: "(none)", total: null },
+ ]);
+ expect(chart.peak).toEqual({
+ series: "2.4.1",
+ time: "2025-09-10T23:00:00.000Z",
+ value: 120,
+ });
+ });
+
+ it.each([
+ ["every accessible project when projectSlug is omitted", null, ["-1"]],
+ [
+ "only the named project",
+ "cloudflare-mcp",
+ [expect.stringMatching(/^\d+$/)],
+ ],
+ ])("charts %s", async (_, projectSlug, expected) => {
+ let projects: string[] | undefined;
+ mswServer.use(
+ http.get(TIMESERIES_URL, ({ request }) => {
+ projects = new URL(request.url).searchParams.getAll("project");
+ return HttpResponse.json({ timeSeries: [] });
+ }),
+ );
+
+ await renderSentryChart.handler({ ...baseParams, projectSlug }, context);
+
+ expect(projects).toEqual(expected);
+ expect(projects).not.toEqual(projectSlug ? ["-1"] : []);
+ });
+
+ it("links grouped errors charts to Discover with the group-by column", async () => {
+ mswServer.use(
+ http.get(TIMESERIES_URL, () => HttpResponse.json({ timeSeries: [] })),
+ );
+
+ const chart = getStructuredContent(
+ await renderSentryChart.handler(
+ { ...baseParams, groupBy: "release" },
+ context,
+ ),
+ );
+
+ expect(new URL(chart.url).searchParams.getAll("field")).toEqual([
+ "release",
+ "count()",
+ ]);
+ });
+
+ it("returns an empty chart when a grouped query matches nothing", async () => {
+ mswServer.use(
+ http.get(TIMESERIES_URL, () => HttpResponse.json({ timeSeries: [] })),
+ );
+
+ const chart = getStructuredContent(
+ await renderSentryChart.handler(
+ { ...baseParams, groupBy: "release" },
+ context,
+ ),
+ );
+
+ expect(chart.series).toEqual([]);
+ expect(chart.peak).toBeNull();
+ });
+
+ it.each([
+ ["start without end", { start: "2025-09-10T00:00:00Z", period: null }],
+ [
+ "period with start and end",
+ { start: "2025-09-10T00:00:00Z", end: "2025-09-11T00:00:00Z" },
+ ],
+ ["grouped profiles", { dataset: "profiles" as const, groupBy: "release" }],
+ ])("rejects %s", async (_, overrides) => {
+ await expect(
+ renderSentryChart.handler({ ...baseParams, ...overrides }, context),
+ ).rejects.toBeInstanceOf(UserInputError);
+ });
+
+ it("rejects an aggregate that returns text", async () => {
+ mswServer.use(
+ http.get(TIMESERIES_URL, () =>
+ HttpResponse.json({
+ timeSeries: [
+ {
+ yAxis: "latest_event()",
+ values: [
+ { timestamp: 1757545200000, value: "abc", incomplete: false },
+ ],
+ meta: { interval: 3600000, valueType: "string" },
+ },
+ ],
+ }),
+ ),
+ );
+
+ await expect(
+ renderSentryChart.handler(
+ { ...baseParams, yAxis: "latest_event()" },
+ context,
+ ),
+ ).rejects.toBeInstanceOf(UserInputError);
+ });
+});
diff --git a/packages/mcp-core/src/tools/catalog/render-sentry-chart.ts b/packages/mcp-core/src/tools/catalog/render-sentry-chart.ts
new file mode 100644
index 0000000000..9c2dbe6345
--- /dev/null
+++ b/packages/mcp-core/src/tools/catalog/render-sentry-chart.ts
@@ -0,0 +1,256 @@
+import { z } from "zod";
+import type { EventsTimeSeriesResponse } from "../../api-client/schema";
+import { UserInputError } from "../../errors";
+import { apiServiceFromContext } from "../../internal/tool-helpers/api";
+import { defineTool } from "../../internal/tool-helpers/define";
+import { structuredResult } from "../../internal/tool-helpers/results";
+import {
+ ParamOrganizationSlug,
+ ParamPeriod,
+ ParamProjectSlug,
+ ParamRegionUrl,
+} from "../../schema";
+import { setTargetTagsAndAttributes } from "../../telem/scope";
+import type { ServerContext } from "../../types";
+import { CHART_UI_RESOURCE, uiToolMeta } from "../../ui-resources";
+import { PUBLIC_EVENTS_DATASETS } from "../../utils/events-datasets";
+import {
+ type ChartResult,
+ renderSentryChartOutputSchema,
+} from "../support/chart/schema";
+import { toStructuredIngestion } from "../support/ingestion";
+import { summarizeSeries } from "../support/search-events/formatters";
+
+/** Top groups plotted when the chart is split by an attribute. */
+const MAX_CHART_SERIES = 5;
+const DEFAULT_PERIOD = "24h";
+
+const INTERVAL_UNITS: [unit: string, ms: number][] = [
+ ["d", 86_400_000],
+ ["h", 3_600_000],
+ ["m", 60_000],
+];
+
+function formatInterval(ms: number): string {
+ for (const [unit, unitMs] of INTERVAL_UNITS) {
+ if (ms % unitMs === 0) return `${ms / unitMs}${unit}`;
+ }
+ return `${ms / 1000}s`;
+}
+
+function seriesLabel(
+ series: EventsTimeSeriesResponse["timeSeries"][number],
+): string {
+ if (!series.groupBy?.length) return series.yAxis;
+ return series.groupBy
+ .map(({ value }) => (value === null || value === "" ? "(none)" : value))
+ .join(", ");
+}
+
+function toChartSeries(
+ response: EventsTimeSeriesResponse,
+ yAxis: string,
+): { series: ChartResult["series"]; peak: ChartResult["peak"] } {
+ let peak: ChartResult["peak"] = null;
+ const series = response.timeSeries.map((entry) => {
+ const label = seriesLabel(entry);
+ const summary = summarizeSeries(entry, yAxis);
+ if (summary.peak && (!peak || summary.peak.value > peak.value)) {
+ peak = {
+ series: label,
+ time: new Date(summary.peak.timestamp).toISOString(),
+ value: summary.peak.value,
+ };
+ }
+ return {
+ label,
+ total: summary.total,
+ buckets: summary.points.map((point) => ({
+ time: new Date(point.timestamp).toISOString(),
+ value: point.value,
+ incomplete: point.filling,
+ outsideRetention: point.outsideRetention,
+ })),
+ };
+ });
+ return { series, peak };
+}
+
+export default defineTool({
+ // MCP Apps views ship to experimental sessions first.
+ experimental: true,
+ includeInSkillDefinitions: false,
+ name: "render_sentry_chart",
+ title: "Render Sentry Chart",
+ skills: ["inspect", "triage", "seer"],
+ requiredScopes: ["event:read"],
+ description:
+ "Chart a count, rate, duration, or other aggregate of Sentry errors, logs, spans, metrics, or profiles over time, optionally split into the top 5 values of one attribute. Returns every bucket of each series, and MCP Apps hosts show it as an interactive chart. To find individual events, use the dataset search tools.",
+ inputSchema: {
+ organizationSlug: ParamOrganizationSlug,
+ regionUrl: ParamRegionUrl.nullable().default(null),
+ dataset: z.enum(PUBLIC_EVENTS_DATASETS).describe("Data to chart."),
+ query: z
+ .string()
+ .trim()
+ .default("")
+ .describe(
+ "Sentry search syntax filter, such as `level:error environment:production`. Empty matches everything.",
+ ),
+ yAxis: z
+ .string()
+ .trim()
+ .min(1)
+ .describe(
+ "Aggregate to plot, such as `count()`, `p95(span.duration)`, or `count_unique(user)`.",
+ ),
+ groupBy: z
+ .string()
+ .trim()
+ .min(1)
+ .nullable()
+ .default(null)
+ .describe(
+ "Attribute to split by, such as `release` or `transaction`; plots its top 5 values. Not supported for profiles.",
+ ),
+ projectSlug: ParamProjectSlug.nullable().default(null),
+ period: ParamPeriod.nullable()
+ .default(null)
+ .describe(
+ "Relative time window, e.g. `1h`, `24h`, `7d`; defaults to 24h. Do not combine with start and end.",
+ ),
+ start: z
+ .string()
+ .trim()
+ .nullable()
+ .default(null)
+ .describe("Absolute start, ISO 8601; requires end."),
+ end: z
+ .string()
+ .trim()
+ .nullable()
+ .default(null)
+ .describe("Absolute end, ISO 8601; requires start."),
+ interval: z
+ .string()
+ .trim()
+ .regex(/^\d+[mhd]$/, "Use a bucket size like `5m`, `1h`, or `1d`.")
+ .nullable()
+ .default(null)
+ .describe("Bucket size such as 5m or 1h. Omit to let Sentry pick."),
+ title: z
+ .string()
+ .trim()
+ .min(1)
+ .nullable()
+ .default(null)
+ .describe("Chart heading; defaults to the aggregate."),
+ },
+ annotations: {
+ readOnlyHint: true,
+ destructiveHint: false,
+ openWorldHint: true,
+ },
+ outputSchema: renderSentryChartOutputSchema,
+ _meta: uiToolMeta(CHART_UI_RESOURCE),
+ async handler(params, context: ServerContext) {
+ if ((params.start === null) !== (params.end === null)) {
+ throw new UserInputError("Pass both `start` and `end`, or neither.");
+ }
+ if (params.start !== null && params.period !== null) {
+ throw new UserInputError(
+ "Pass either `period` or `start` and `end`, not both.",
+ );
+ }
+ if (params.groupBy !== null && params.dataset === "profiles") {
+ throw new UserInputError(
+ "Sentry cannot split profile charts by an attribute. Remove `groupBy`.",
+ );
+ }
+
+ const apiService = apiServiceFromContext(context, {
+ regionUrl: params.regionUrl ?? undefined,
+ });
+ const organizationSlug = params.organizationSlug;
+ setTargetTagsAndAttributes({
+ organizationSlug,
+ projectSlug: params.projectSlug ?? undefined,
+ });
+
+ // Without a project, Sentry only charts projects whose teams the user
+ // belongs to. `-1` covers every project the user can access, as the UI's
+ // "All Projects" does.
+ let projectId = "-1";
+ if (params.projectSlug) {
+ const project = await apiService.getProject({
+ organizationSlug,
+ projectSlugOrId: params.projectSlug,
+ });
+ projectId = String(project.id);
+ }
+
+ const timeParams: { statsPeriod?: string; start?: string; end?: string } =
+ params.start !== null && params.end !== null
+ ? { start: params.start, end: params.end }
+ : { statsPeriod: params.period ?? DEFAULT_PERIOD };
+ const response = await apiService.getEventsTimeSeries({
+ organizationSlug,
+ query: params.query,
+ yAxis: params.yAxis,
+ interval: params.interval ?? undefined,
+ projectId,
+ dataset: params.dataset,
+ ...timeParams,
+ topEvents: params.groupBy
+ ? { groupBy: params.groupBy, limit: MAX_CHART_SERIES }
+ : undefined,
+ });
+
+ const meta = response.timeSeries[0]?.meta;
+ if (meta?.valueType === "string") {
+ throw new UserInputError(
+ `\`${params.yAxis}\` returns text, which cannot be charted. Use a numeric aggregate such as \`count()\`.`,
+ );
+ }
+ const { series, peak } = toChartSeries(response, params.yAxis);
+
+ return structuredResult({
+ title:
+ params.title ??
+ (params.groupBy
+ ? `${params.yAxis} by ${params.groupBy}`
+ : params.yAxis),
+ dataset: params.dataset,
+ query: params.query,
+ yAxis: params.yAxis,
+ groupBy: params.groupBy,
+ valueType: meta?.valueType ?? null,
+ valueUnit: meta?.valueUnit ?? null,
+ interval: meta
+ ? formatInterval(meta.interval)
+ : (params.interval ?? "auto"),
+ timeRange: {
+ statsPeriod: timeParams.statsPeriod ?? null,
+ start: timeParams.start ?? null,
+ end: timeParams.end ?? null,
+ },
+ url: apiService.getEventsExplorerUrl(
+ organizationSlug,
+ params.query,
+ projectId,
+ params.dataset,
+ // Discover reads group-by columns from `field`, so list it first.
+ params.groupBy ? [params.groupBy, params.yAxis] : [params.yAxis],
+ `-${params.yAxis}`,
+ [params.yAxis],
+ params.groupBy ? [params.groupBy] : [],
+ timeParams.statsPeriod,
+ timeParams.start,
+ timeParams.end,
+ ),
+ series,
+ peak,
+ ingestion: toStructuredIngestion(response.meta?.ingestion),
+ });
+ },
+});
diff --git a/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts b/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts
index 266b25a1f0..39e26250f0 100644
--- a/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts
+++ b/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts
@@ -346,7 +346,20 @@ describe("search_errors structured output", () => {
"query": "errors per hour",
"resultType": "timeSeries",
"results": [],
- "suggestedActions": [],
+ "suggestedActions": [
+ {
+ "arguments": {
+ "dataset": "errors",
+ "organizationSlug": "test-org",
+ "period": "24h",
+ "query": "level:error",
+ "yAxis": "count()",
+ },
+ "reason": "Chart every bucket of this series.",
+ "toolName": "render_sentry_chart",
+ "type": "tool_call",
+ },
+ ],
"timeSeries": {
"bucketCount": 4,
"buckets": [
diff --git a/packages/mcp-core/src/tools/support/chart/schema.ts b/packages/mcp-core/src/tools/support/chart/schema.ts
new file mode 100644
index 0000000000..00034948eb
--- /dev/null
+++ b/packages/mcp-core/src/tools/support/chart/schema.ts
@@ -0,0 +1,62 @@
+/**
+ * The render_sentry_chart result. Imports only zod, so the chart view parses
+ * the same contract the tool declares.
+ */
+import { z } from "zod";
+import { ingestionSchema } from "../ingestion";
+
+const chartBucketSchema = z.object({
+ time: z.string(),
+ value: z.number(),
+ incomplete: z
+ .boolean()
+ .describe("Data is still arriving, so the value may rise."),
+ outsideRetention: z
+ .boolean()
+ .describe(
+ "Starts before the retention window, so older data is missing and the value will not change.",
+ ),
+});
+
+export const renderSentryChartOutputSchema = z.object({
+ title: z.string(),
+ dataset: z.string(),
+ query: z.string(),
+ yAxis: z.string(),
+ groupBy: z.string().nullable(),
+ valueType: z
+ .string()
+ .nullable()
+ .describe("Such as integer, number, duration, percentage, or size."),
+ valueUnit: z.string().nullable().describe("Such as millisecond or byte."),
+ interval: z.string().describe("Bucket size, such as 5m or 1h."),
+ timeRange: z.object({
+ statsPeriod: z.string().nullable(),
+ start: z.string().nullable(),
+ end: z.string().nullable(),
+ }),
+ url: z.string(),
+ series: z
+ .array(
+ z.object({
+ label: z
+ .string()
+ .describe("The group's value, or the aggregate when ungrouped."),
+ total: z
+ .number()
+ .nullable()
+ .describe("Sum of all buckets; null for non-additive aggregates."),
+ buckets: z
+ .array(chartBucketSchema)
+ .describe("Every bucket, oldest first."),
+ }),
+ )
+ .describe("One series, or one per top group, largest first."),
+ peak: z
+ .object({ series: z.string(), time: z.string(), value: z.number() })
+ .nullable()
+ .describe("Highest bucket across series that is no longer receiving data."),
+ ingestion: ingestionSchema,
+});
+
+export type ChartResult = z.output;
diff --git a/packages/mcp-core/src/tools/support/ingestion.ts b/packages/mcp-core/src/tools/support/ingestion.ts
new file mode 100644
index 0000000000..a388a46440
--- /dev/null
+++ b/packages/mcp-core/src/tools/support/ingestion.ts
@@ -0,0 +1,29 @@
+/**
+ * Ingestion delay in structured time series results. Imports only zod, so the
+ * chart view can share it.
+ */
+import { z } from "zod";
+import type { IngestionMeta } from "../../api-client/schema";
+
+export const ingestionSchema = z
+ .object({
+ status: z.string(),
+ delaySeconds: z.number().nullable(),
+ completeThrough: z.string().nullable(),
+ })
+ .nullable();
+
+export function toStructuredIngestion(
+ ingestion: IngestionMeta | undefined,
+): z.output {
+ return ingestion
+ ? {
+ status: ingestion.status,
+ delaySeconds: ingestion.delaySeconds ?? null,
+ completeThrough:
+ ingestion.completeThrough === undefined
+ ? null
+ : new Date(ingestion.completeThrough).toISOString(),
+ }
+ : null;
+}
diff --git a/packages/mcp-core/src/tools/support/search-events/formatters.ts b/packages/mcp-core/src/tools/support/search-events/formatters.ts
index a36d05fe29..e380db3130 100644
--- a/packages/mcp-core/src/tools/support/search-events/formatters.ts
+++ b/packages/mcp-core/src/tools/support/search-events/formatters.ts
@@ -989,7 +989,7 @@ function formatIngestionStatus(ingestion: IngestionMeta): string {
return `- **Ingestion**: ${ingestion.status}${detail}`;
}
-interface TimeSeriesPoint {
+export interface TimeSeriesPoint {
timestamp: number;
time: string;
/** Sort key: the number, or parsed time for date-typed strings. */
@@ -1001,62 +1001,61 @@ interface TimeSeriesPoint {
outsideRetention: boolean;
}
-interface TimeSeriesSummary {
+/** One series of an events-timeseries result, with every bucket. */
+export interface SeriesSummary {
/** Every bucket, oldest first. */
- bucketCount: number;
- /** The most recent `MAX_TIME_SERIES_ROWS` buckets. */
- shown: TimeSeriesPoint[];
+ points: TimeSeriesPoint[];
total: number | null;
hasFilling: boolean;
peak: TimeSeriesPoint | undefined;
+}
+
+interface TimeSeriesSummary extends Omit {
+ bucketCount: number;
+ /** The most recent `MAX_TIME_SERIES_ROWS` buckets. */
+ shown: TimeSeriesPoint[];
ingestion: IngestionMeta | undefined;
}
const MAX_TIME_SERIES_ROWS = 48;
/**
- * Summarize an events-timeseries result: a metric bucketed over time.
+ * Summarize one series: a metric bucketed over time.
* Buckets flagged `incomplete` by Sentry are still receiving data and are
* excluded from the peak; those that start before the retention window are
* permanently partial and will not change.
*/
-export function summarizeTimeSeries(
- series: EventsTimeSeriesResponse,
+export function summarizeSeries(
+ series: EventsTimeSeriesResponse["timeSeries"][number] | undefined,
yAxis: string,
-): TimeSeriesSummary {
+): SeriesSummary {
// String aggregates can return identifiers, even when their values look numeric.
- const isStringSeries = series.timeSeries[0]?.meta.valueType === "string";
- const points = (series.timeSeries[0]?.values ?? []).map(
- (bucket): TimeSeriesPoint => {
- // OUTSIDE_RETENTION buckets start before the retention window: their data
- // is permanently partial. Every other reason means data is still arriving.
- const outsideRetention =
- bucket.incomplete && bucket.incompleteReason === "OUTSIDE_RETENTION";
- const raw = bucket.value ?? 0;
- // Date-typed aggregates such as max(timestamp) return ISO datetime
- // strings. Number() rejects those whole (parseFloat would keep the year),
- // so order them by parsed time and display the raw string.
- const numeric = typeof raw === "number" ? raw : Number(raw);
- const isNumeric = !Number.isNaN(numeric);
- const keepsNumber = !isStringSeries && isNumeric;
- return {
- timestamp: bucket.timestamp,
- time: formatBucketTime(bucket.timestamp),
- value: isNumeric ? numeric : Date.parse(String(raw)) || 0,
- rawValue: keepsNumber ? numeric : String(raw),
- display: keepsNumber ? numeric.toLocaleString() : String(raw),
- filling: bucket.incomplete && !outsideRetention,
- outsideRetention,
- };
- },
- );
+ const isStringSeries = series?.meta.valueType === "string";
+ const points = (series?.values ?? []).map((bucket): TimeSeriesPoint => {
+ // OUTSIDE_RETENTION buckets start before the retention window: their data
+ // is permanently partial. Every other reason means data is still arriving.
+ const outsideRetention =
+ bucket.incomplete && bucket.incompleteReason === "OUTSIDE_RETENTION";
+ const raw = bucket.value ?? 0;
+ // Date-typed aggregates such as max(timestamp) return ISO datetime
+ // strings. Number() rejects those whole (parseFloat would keep the year),
+ // so order them by parsed time and display the raw string.
+ const numeric = typeof raw === "number" ? raw : Number(raw);
+ const isNumeric = !Number.isNaN(numeric);
+ const keepsNumber = !isStringSeries && isNumeric;
+ return {
+ timestamp: bucket.timestamp,
+ time: formatBucketTime(bucket.timestamp),
+ value: isNumeric ? numeric : Date.parse(String(raw)) || 0,
+ rawValue: keepsNumber ? numeric : String(raw),
+ display: keepsNumber ? numeric.toLocaleString() : String(raw),
+ filling: bucket.incomplete && !outsideRetention,
+ outsideRetention,
+ };
+ });
return {
- bucketCount: points.length,
- shown:
- points.length > MAX_TIME_SERIES_ROWS
- ? points.slice(-MAX_TIME_SERIES_ROWS)
- : points,
+ points,
// Total is only meaningful for additive aggregates; summing count_unique /
// avg / percentile buckets would be wrong, so omit it for those.
total:
@@ -1072,6 +1071,22 @@ export function summarizeTimeSeries(
(max, p) => (max === undefined || p.value > max.value ? p : max),
undefined,
),
+ };
+}
+
+/** Summarize an ungrouped events-timeseries result, keeping recent buckets. */
+export function summarizeTimeSeries(
+ series: EventsTimeSeriesResponse,
+ yAxis: string,
+): TimeSeriesSummary {
+ const { points, ...summary } = summarizeSeries(series.timeSeries[0], yAxis);
+ return {
+ ...summary,
+ bucketCount: points.length,
+ shown:
+ points.length > MAX_TIME_SERIES_ROWS
+ ? points.slice(-MAX_TIME_SERIES_ROWS)
+ : points,
ingestion: series.meta?.ingestion,
};
}
diff --git a/packages/mcp-core/src/tools/support/search-events/search.ts b/packages/mcp-core/src/tools/support/search-events/search.ts
index 2d6a076636..6eeda9581d 100644
--- a/packages/mcp-core/src/tools/support/search-events/search.ts
+++ b/packages/mcp-core/src/tools/support/search-events/search.ts
@@ -1224,6 +1224,15 @@ async function executeSearchEvents(
notes: droppedEventsNote
? [...notesFor(pointsWithData), droppedEventsNote]
: notesFor(pointsWithData),
+ session: {
+ apiService,
+ organizationSlug,
+ experimentalMode: context.experimentalMode ?? false,
+ availableToolNames: context.availableToolNames,
+ directToolNames: context.directToolNames,
+ },
+ projectSlug: params.projectSlug,
+ regionUrl: params.regionUrl,
});
}
const timeSeriesOutput = formatTimeSeriesResults({
diff --git a/packages/mcp-core/src/tools/support/search-events/structured.ts b/packages/mcp-core/src/tools/support/search-events/structured.ts
index f9d62dddce..1d2f0a56d7 100644
--- a/packages/mcp-core/src/tools/support/search-events/structured.ts
+++ b/packages/mcp-core/src/tools/support/search-events/structured.ts
@@ -30,6 +30,7 @@ import {
type SearchResultHints,
summarizeTimeSeries,
} from "./formatters";
+import { ingestionSchema, toStructuredIngestion } from "../ingestion";
import { type FlexibleEventData, isAggregateQuery } from "./utils";
export const timeRangeSchema = z.object({
@@ -64,13 +65,7 @@ const timeSeriesSchema = z.object({
})
.nullable()
.describe("Highest bucket that is no longer receiving data."),
- ingestion: z
- .object({
- status: z.string(),
- delaySeconds: z.number().nullable(),
- completeThrough: z.string().nullable(),
- })
- .nullable(),
+ ingestion: ingestionSchema,
bucketCount: z.number(),
buckets: z
.array(
@@ -455,9 +450,33 @@ export function buildStructuredTimeSeriesResult(params: {
timeRange: { statsPeriod?: string; start?: string; end?: string };
url: string;
notes: string[];
+ session: StructuredSearchSession;
+ projectSlug: string | null;
+ regionUrl: string | null;
}): StructuredToolOutput {
const { bucketCount, shown, total, hasFilling, peak, ingestion } =
summarizeTimeSeries(params.series, params.yAxis);
+ const { session, timeRange } = params;
+ const chartAction = buildSuggestedToolAction({
+ toolName: "render_sentry_chart",
+ arguments: {
+ organizationSlug: session.organizationSlug,
+ dataset: params.dataset,
+ query: params.query,
+ yAxis: params.yAxis,
+ ...(timeRange.start && timeRange.end
+ ? { start: timeRange.start, end: timeRange.end }
+ : timeRange.statsPeriod
+ ? { period: timeRange.statsPeriod }
+ : {}),
+ ...(params.projectSlug && { projectSlug: params.projectSlug }),
+ ...(params.regionUrl && { regionUrl: params.regionUrl }),
+ },
+ reason: "Chart every bucket of this series.",
+ experimentalMode: session.experimentalMode,
+ availableToolNames: session.availableToolNames,
+ directToolNames: session.directToolNames,
+ });
return structuredResult({
query: params.inputQuery,
@@ -484,16 +503,7 @@ export function buildStructuredTimeSeriesResult(params: {
peak: peak
? { time: new Date(peak.timestamp).toISOString(), value: peak.rawValue }
: null,
- ingestion: ingestion
- ? {
- status: ingestion.status,
- delaySeconds: ingestion.delaySeconds ?? null,
- completeThrough:
- ingestion.completeThrough === undefined
- ? null
- : new Date(ingestion.completeThrough).toISOString(),
- }
- : null,
+ ingestion: toStructuredIngestion(ingestion),
bucketCount,
buckets: shown.map((point) => ({
time: new Date(point.timestamp).toISOString(),
@@ -502,6 +512,6 @@ export function buildStructuredTimeSeriesResult(params: {
outsideRetention: point.outsideRetention,
})),
},
- suggestedActions: [],
+ suggestedActions: chartAction ? [chartAction] : [],
});
}
diff --git a/packages/mcp-core/src/tools/types.ts b/packages/mcp-core/src/tools/types.ts
index e453e93325..083c457261 100644
--- a/packages/mcp-core/src/tools/types.ts
+++ b/packages/mcp-core/src/tools/types.ts
@@ -170,6 +170,12 @@ export interface ToolConfig<
idempotentHint?: boolean;
openWorldHint: boolean;
};
+ /**
+ * MCP `_meta` sent with the tool in tools/list, for keys that hosts read,
+ * such as `ui.resourceUri` (MCP Apps). Every key must be listed in
+ * `ALLOWED_TOOL_META` in server.metadata.test.ts.
+ */
+ _meta?: Record;
handler: ToolHandler>;
/**
* Optional hook invoked when the handler throws, for tool-specific failure
diff --git a/packages/mcp-core/src/ui-resources.test.ts b/packages/mcp-core/src/ui-resources.test.ts
new file mode 100644
index 0000000000..cddf348fbb
--- /dev/null
+++ b/packages/mcp-core/src/ui-resources.test.ts
@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { uiResourceProblems } from "./test-utils/ui-resource-policy";
+import tools from "./tools";
+import {
+ CHART_UI_RESOURCE,
+ UI_RESOURCES,
+ type UiResource,
+} from "./ui-resources";
+
+const catalog = Object.entries(tools).map(([name, tool]) => ({
+ name,
+ _meta: tool._meta,
+}));
+
+const html = "";
+const view: UiResource = {
+ uri: "ui://sentry/test/v1.html",
+ name: "test",
+ title: "Test",
+ description: "Test view",
+ htmlSha256: createHash("sha256").update(html).digest("hex"),
+ budgetBytes: 1024,
+ loadHtml: async () => html,
+ meta: { csp: {} },
+};
+const tool = { name: "test_tool", _meta: { ui: { resourceUri: view.uri } } };
+
+describe("UI resources", () => {
+ it("follow every MCP Apps rule in the tool catalog", async () => {
+ expect(await uiResourceProblems(catalog, UI_RESOURCES)).toEqual([]);
+ });
+
+ it("has a view for render_sentry_chart", () => {
+ expect(tools.render_sentry_chart._meta).toEqual({
+ ui: { resourceUri: CHART_UI_RESOURCE.uri },
+ "openai/outputTemplate": CHART_UI_RESOURCE.uri,
+ });
+ });
+});
+
+describe("uiResourceProblems", () => {
+ it("passes a valid view", async () => {
+ expect(await uiResourceProblems([tool], [view])).toEqual([]);
+ });
+
+ it("fails when a tool names a view that does not exist", async () => {
+ const stray = {
+ name: "stray",
+ _meta: { ui: { resourceUri: "ui://x/v1" } },
+ };
+
+ expect(await uiResourceProblems([tool, stray], [view])).toEqual([
+ `stray names view "ui://x/v1", which is not a UI resource.`,
+ ]);
+ });
+
+ it("fails when no tool names a view", async () => {
+ expect(await uiResourceProblems([], [view])).toEqual([
+ `No tool names ${view.uri}, so it is never listed.`,
+ ]);
+ });
+
+ it("fails an unversioned URI", async () => {
+ const unversioned = { ...view, uri: "ui://sentry/test.html" as const };
+ const named = {
+ name: "t",
+ _meta: { ui: { resourceUri: unversioned.uri } },
+ };
+
+ expect(await uiResourceProblems([named], [unversioned])).toEqual([
+ expect.stringContaining("has no version"),
+ ]);
+ });
+
+ it("fails a csp that allows an origin", async () => {
+ const leaky = {
+ ...view,
+ meta: { csp: { connectDomains: ["https://sentry.io"] } },
+ };
+
+ expect(await uiResourceProblems([tool], [leaky])).toEqual([
+ expect.stringContaining("allows connectDomains in its csp"),
+ ]);
+ });
+
+ it("fails when the HTML changes but the recorded hash does not", async () => {
+ const edited = { ...view, loadHtml: async () => `${html}\n` };
+
+ expect(await uiResourceProblems([tool], [edited])).toEqual([
+ expect.stringContaining(`The HTML of ${view.uri} changed`),
+ ]);
+ });
+});
diff --git a/packages/mcp-core/src/ui-resources.ts b/packages/mcp-core/src/ui-resources.ts
new file mode 100644
index 0000000000..b2000609c4
--- /dev/null
+++ b/packages/mcp-core/src/ui-resources.ts
@@ -0,0 +1,135 @@
+/**
+ * MCP Apps views: `ui://` HTML resources that a host renders inline for a
+ * tool result. A tool opts in with `_meta: uiToolMeta(resource)`, and the
+ * server lists each resource that a registered tool references.
+ * Views are generated HTML strings, so they need no file system at runtime.
+ *
+ * Spec: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+ */
+import type { McpServer } from "@modelcontextprotocol/server";
+
+/** The MIME type of an MCP Apps view. */
+export const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+
+/** `_meta.ui` on a tool: the view that renders its results. */
+export interface UiToolMeta {
+ resourceUri: string;
+}
+
+/**
+ * `_meta.ui` on a view resource. Each `csp` list names origins that the host
+ * may allow; an empty `csp` means the view loads nothing from the network.
+ */
+export interface UiResourceMeta {
+ csp: {
+ connectDomains?: string[];
+ resourceDomains?: string[];
+ frameDomains?: string[];
+ baseUriDomains?: string[];
+ };
+ prefersBorder?: boolean;
+}
+
+export interface UiResource {
+ /** Hosts cache a view by its URI, so bump the version when the HTML changes. */
+ uri: `ui://${string}`;
+ name: string;
+ title: string;
+ description: string;
+ /**
+ * SHA-256 of the HTML that `uri` serves. A test fails when the HTML changes
+ * and this does not, so a change also bumps the version in `uri`.
+ */
+ htmlSha256: string;
+ /** Most bytes the HTML may take. The view's generator fails over it. */
+ budgetBytes: number;
+ /**
+ * Loads the self-contained HTML5 document (inline scripts and styles only)
+ * on the first `resources/read`, so sessions that never render a view do
+ * not load it.
+ */
+ loadHtml(): Promise;
+ meta: UiResourceMeta;
+}
+
+/** The render_sentry_chart view. Built from chart-app/ by generate-chart-app. */
+export const CHART_UI_RESOURCE: UiResource = {
+ uri: "ui://sentry/chart/v1.html",
+ name: "sentry_chart",
+ title: "Sentry Chart",
+ description:
+ "Interactive time series chart for render_sentry_chart results, with a range picker and a link to Sentry.",
+ htmlSha256:
+ "c42d34d3aa082a33b4ab293b509dbe4b2dbde7edc4965033cffa8b920fc6e39f",
+ // About 1.5x the current view, so a new dependency cannot slip in.
+ budgetBytes: 24 * 1024,
+ loadHtml: async () =>
+ (await import("./ui/chart-app.generated")).CHART_APP_HTML,
+ // Self-contained, so it loads nothing from the network.
+ meta: { csp: {}, prefersBorder: true },
+};
+
+export const UI_RESOURCES: readonly UiResource[] = [CHART_UI_RESOURCE];
+
+/**
+ * `_meta` for a tool whose result renders in `resource`. ChatGPT reads
+ * `openai/outputTemplate`; MCP Apps hosts read `ui.resourceUri`.
+ */
+export function uiToolMeta(resource: UiResource): {
+ ui: UiToolMeta;
+ "openai/outputTemplate": string;
+} {
+ return {
+ ui: { resourceUri: resource.uri },
+ "openai/outputTemplate": resource.uri,
+ };
+}
+
+function referencedResourceUri(
+ meta: Record | undefined,
+): string | undefined {
+ const ui = meta?.["ui"];
+ if (typeof ui !== "object" || ui === null || !("resourceUri" in ui)) {
+ return undefined;
+ }
+ return typeof ui.resourceUri === "string" ? ui.resourceUri : undefined;
+}
+
+/** Lists the views that the registered tools reference. */
+export function registerUiResources(
+ server: McpServer,
+ tools: readonly { _meta?: Record | undefined }[],
+): void {
+ const referenced = new Set(
+ tools.map((tool) => referencedResourceUri(tool._meta)),
+ );
+ const resources = UI_RESOURCES.filter((resource) =>
+ referenced.has(resource.uri),
+ );
+ for (const resource of resources) {
+ server.registerResource(
+ resource.name,
+ resource.uri,
+ {
+ title: resource.title,
+ description: resource.description,
+ mimeType: UI_RESOURCE_MIME_TYPE,
+ _meta: { ui: resource.meta },
+ },
+ async () => ({
+ contents: [
+ {
+ uri: resource.uri,
+ mimeType: UI_RESOURCE_MIME_TYPE,
+ text: await resource.loadHtml(),
+ _meta: { ui: resource.meta },
+ },
+ ],
+ }),
+ );
+ }
+ // Registration enables this by default, but the set of views is fixed.
+ if (resources.length > 0) {
+ server.server.registerCapabilities({ resources: { listChanged: false } });
+ }
+}
diff --git a/packages/mcp-core/src/ui/chart-app.generated.ts b/packages/mcp-core/src/ui/chart-app.generated.ts
new file mode 100644
index 0000000000..ff36828222
--- /dev/null
+++ b/packages/mcp-core/src/ui/chart-app.generated.ts
@@ -0,0 +1,2 @@
+// Generated by scripts/generate-chart-app.ts from chart-app/. Do not edit.
+export const CHART_APP_HTML = "Sentry chart";
diff --git a/packages/mcp-server-mocks/src/events-timeseries.ts b/packages/mcp-server-mocks/src/events-timeseries.ts
new file mode 100644
index 0000000000..608d748c47
--- /dev/null
+++ b/packages/mcp-server-mocks/src/events-timeseries.ts
@@ -0,0 +1,102 @@
+/**
+ * Deterministic `events-timeseries` responses. The series ends at a fixed
+ * time and its bucket size follows the requested range, so a chart drawn
+ * from it looks the same on every run and changes shape when the range does.
+ */
+import { HttpResponse } from "msw";
+
+const SERIES_END = Date.UTC(2025, 8, 11, 0, 0, 0);
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/** Bucket size per range when the request names no interval. */
+const DEFAULT_INTERVALS: [rangeMs: number, intervalMs: number][] = [
+ [HOUR, MINUTE],
+ [DAY, 30 * MINUTE],
+ [7 * DAY, 3 * HOUR],
+ [Number.POSITIVE_INFINITY, 6 * HOUR],
+];
+
+const UNIT_MS: Record = {
+ s: 1000,
+ m: MINUTE,
+ h: HOUR,
+ d: DAY,
+ w: 7 * DAY,
+};
+
+function parseDuration(value: string | null): number | undefined {
+ const match = value ? /^(\d+)([smhdw])$/.exec(value) : null;
+ const unit = match?.[2];
+ return match && unit ? Number(match[1]) * (UNIT_MS[unit] ?? 0) : undefined;
+}
+
+const GROUP_VALUES = ["frontend@2.4.1", "frontend@2.4.0", "frontend@2.3.9"];
+
+export function eventsTimeSeriesResponse(request: Request): Response {
+ const params = new URL(request.url).searchParams;
+ const yAxis = params.get("yAxis");
+ if (!params.get("dataset") || !yAxis) {
+ return HttpResponse.json(
+ { detail: "dataset and yAxis are required" },
+ { status: 400 },
+ );
+ }
+ const topEvents = params.get("topEvents");
+ const groupBy = params.get("groupBy");
+ if (topEvents && (!groupBy || !params.get("sort"))) {
+ return HttpResponse.json(
+ { detail: "groupBy is a required parameter when doing topEvents" },
+ { status: 400 },
+ );
+ }
+
+ const start = params.get("start");
+ const end = params.get("end");
+ const [rangeStart, rangeEnd] =
+ start && end
+ ? [Date.parse(start), Date.parse(end)]
+ : [
+ SERIES_END - (parseDuration(params.get("statsPeriod")) ?? 14 * DAY),
+ SERIES_END,
+ ];
+ const range = rangeEnd - rangeStart;
+ const interval =
+ parseDuration(params.get("interval")) ??
+ DEFAULT_INTERVALS.find(([limit]) => range <= limit)?.[1] ??
+ 6 * HOUR;
+ const bucketCount = Math.max(1, Math.round(range / interval));
+
+ const groups = groupBy
+ ? GROUP_VALUES.slice(0, Number(topEvents) || GROUP_VALUES.length)
+ : [null];
+ const isDuration = /duration/.test(yAxis);
+ const timeSeries = groups.map((group, groupIndex) => ({
+ yAxis,
+ ...(group !== null && { groupBy: [{ key: groupBy, value: group }] }),
+ values: Array.from({ length: bucketCount }, (_, index) => {
+ const wave = Math.sin((index / bucketCount) * Math.PI * 4 + groupIndex);
+ const spike = index === Math.floor(bucketCount * 0.7) ? 2.5 : 1;
+ const base = (isDuration ? 180 : 40) / (groupIndex + 1);
+ const isLast = index === bucketCount - 1;
+ return {
+ timestamp: rangeEnd - (bucketCount - index) * interval,
+ value: Math.round(base * (1.4 + wave) * spike),
+ incomplete: isLast,
+ ...(isLast && { incompleteReason: "INGESTION_PENDING" }),
+ };
+ }),
+ meta: {
+ interval,
+ valueType: isDuration ? "duration" : "integer",
+ valueUnit: isDuration ? "millisecond" : null,
+ ...(group !== null && { order: groupIndex, isOther: false }),
+ },
+ }));
+
+ return HttpResponse.json({
+ timeSeries,
+ meta: { start: rangeStart, end: rangeEnd },
+ });
+}
diff --git a/packages/mcp-server-mocks/src/index.ts b/packages/mcp-server-mocks/src/index.ts
index 268be4de11..b085631932 100644
--- a/packages/mcp-server-mocks/src/index.ts
+++ b/packages/mcp-server-mocks/src/index.ts
@@ -85,6 +85,7 @@ import uptimeChecksFixture from "./fixtures/uptime-checks.json" with { type: "js
import uptimeMonitorFixture from "./fixtures/uptime-monitor.json" with { type: "json" };
import userFixture from "./fixtures/user.json" with { type: "json" };
import { issueFixture2 } from "./payloads";
+import { eventsTimeSeriesResponse } from "./events-timeseries";
/**
* Builds MSW handlers for both SaaS and self-hosted Sentry instances.
@@ -563,6 +564,11 @@ export const restHandlers: HttpHandler[] = buildHandlers([
});
},
},
+ {
+ method: "get",
+ path: "/api/0/organizations/sentry-mcp-evals/events-timeseries/",
+ fetch: ({ request }) => eventsTimeSeriesResponse(request),
+ },
{
method: "get",
path: "/api/0/organizations/sentry-mcp-evals/events/",
diff --git a/packages/mcp-server/script/bundle.ts b/packages/mcp-server/script/bundle.ts
index 47fe9b8b52..b54df7db82 100644
--- a/packages/mcp-server/script/bundle.ts
+++ b/packages/mcp-server/script/bundle.ts
@@ -23,9 +23,9 @@ const CLI_ROOT = resolve(PACKAGE_ROOT, "../cli");
const OUTFILE = resolve(PACKAGE_ROOT, "dist/sentry-mcp.cjs");
/**
- * Output is 3,624,475 bytes (3.46 MiB) once help's image banner is left out.
- * The budget leaves about 300 KB for new tools and commands, not enough for a
- * heavy CLI dependency to slip in unnoticed.
+ * Output is 3,902,133 bytes (3.72 MiB) once help's image banner is left out,
+ * 17 KB of it the inlined render_sentry_chart MCP Apps view. The budget
+ * leaves about 30 KB, so a heavy dependency or view cannot slip in unnoticed.
*/
const MAX_BUNDLE_BYTES = 3.75 * 1024 * 1024;
diff --git a/plugins/sentry-mcp-experimental/agents/sentry-mcp.md b/plugins/sentry-mcp-experimental/agents/sentry-mcp.md
index 17eb42990a..65124e5830 100644
--- a/plugins/sentry-mcp-experimental/agents/sentry-mcp.md
+++ b/plugins/sentry-mcp-experimental/agents/sentry-mcp.md
@@ -63,6 +63,7 @@ allowedTools:
- link_issue
- onboarding_status_update
- remove_team_from_project
+ - render_sentry_chart
- search_agent_conversations
- search_attributes
- search_docs
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a3ee071ae2..d31e4395bb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -195,6 +195,15 @@ catalogs:
'@cloudflare/workers-types':
specifier: ^4.20260405.1
version: 4.20260405.1
+ '@modelcontextprotocol/client':
+ specifier: 2.4.0
+ version: 2.4.0
+ '@modelcontextprotocol/core':
+ specifier: 2.4.0
+ version: 2.4.0
+ '@modelcontextprotocol/ext-apps':
+ specifier: 2.0.4
+ version: 2.0.4
'@modelcontextprotocol/server':
specifier: 2.4.0
version: 2.4.0
@@ -312,6 +321,9 @@ catalogs:
oxlint:
specifier: 1.93.0
version: 1.93.0
+ playwright-core:
+ specifier: 1.65.1
+ version: 1.65.1
react:
specifier: ^19.2.8
version: 19.2.8
@@ -1058,15 +1070,30 @@ importers:
'@ai-sdk/provider-utils':
specifier: ^4.0.33
version: 4.0.40(zod@4.6.7)
+ '@modelcontextprotocol/client':
+ specifier: 'catalog:'
+ version: 2.4.0
+ '@modelcontextprotocol/core':
+ specifier: 'catalog:'
+ version: 2.4.0
+ '@modelcontextprotocol/ext-apps':
+ specifier: 'catalog:'
+ version: 2.0.4(@modelcontextprotocol/client@2.4.0)(@modelcontextprotocol/core@2.4.0)(@modelcontextprotocol/server@2.4.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.7)
'@modelcontextprotocol/sdk':
specifier: 1.32.2
version: 1.32.2(@cfworker/json-schema@4.1.1)(supports-color@10.1.0)(zod@4.6.7)
'@sentry/mcp-server-mocks':
specifier: workspace:*
version: link:../mcp-server-mocks
+ esbuild:
+ specifier: ^0.28.1
+ version: 0.28.2
msw:
specifier: 'catalog:'
version: 2.15.0(@types/node@22.20.3)(typescript@7.0.2)
+ playwright-core:
+ specifier: 'catalog:'
+ version: 1.65.1
tiktoken:
specifier: ^1.0.18
version: 1.0.22
@@ -2991,6 +3018,24 @@ packages:
resolution: {integrity: sha512-z8QBKqdfXLPzkLQuG4xp8hrVEMm1PZ1IgxMN2sMbJiFiAKOWXnAzogXn2W4aqIBlP1ea6U5yiqVquvUNM1Cj6Q==}
engines: {node: '>=20'}
+ '@modelcontextprotocol/ext-apps@2.0.4':
+ resolution: {integrity: sha512-B+PcbuGiaf0e5I3uy4iO5tS3Abo+5w8JvZFzHMzQdq9yVwP836zJkw2+KCGOQ0r4TM1fuQi4JdnbuWjkS4aBvg==}
+ engines: {node: '>=20'}
+ peerDependencies:
+ '@modelcontextprotocol/client': ^2.0.0
+ '@modelcontextprotocol/core': ^2.0.0
+ '@modelcontextprotocol/server': ^2.0.0
+ react: ^17.0.0 || ^18.0.0 || ^19.0.0
+ react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+ zod: ^4.6.6
+ peerDependenciesMeta:
+ '@modelcontextprotocol/server':
+ optional: true
+ react:
+ optional: true
+ react-dom:
+ optional: true
+
'@modelcontextprotocol/sdk@1.32.2':
resolution: {integrity: sha512-SWsVtH/0vULSQStoZ6xxH2K09Li8fXYTMC64ZeogCdpZ3XSi1eCPOByV1OpuJxuI3OcmHhosDWYyii07tpPsLw==}
engines: {node: '>=18'}
@@ -7354,6 +7399,11 @@ packages:
resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
engines: {node: '>=16.20.0'}
+ playwright-core@1.65.1:
+ resolution: {integrity: sha512-hqPpz7blSMPxWVdoeE1yiBSzXsKiVOd2k+kjCvmUywD2GPO2Dd9HfcWnq9NN0GHbNZDFgZ9JfBFr+X5/BLo0qw==}
+ engines: {node: '>=20'}
+ hasBin: true
+
pngjs@7.0.0:
resolution: {integrity: sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==}
engines: {node: '>=14.19.0'}
@@ -10422,6 +10472,17 @@ snapshots:
dependencies:
zod: 4.6.7
+ '@modelcontextprotocol/ext-apps@2.0.4(@modelcontextprotocol/client@2.4.0)(@modelcontextprotocol/core@2.4.0)(@modelcontextprotocol/server@2.4.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.7)':
+ dependencies:
+ '@modelcontextprotocol/client': 2.4.0
+ '@modelcontextprotocol/core': 2.4.0
+ '@standard-schema/spec': 1.1.0
+ zod: 4.6.7
+ optionalDependencies:
+ '@modelcontextprotocol/server': 2.4.0
+ react: 19.2.8
+ react-dom: 19.2.8(react@19.2.8)
+
'@modelcontextprotocol/sdk@1.32.2(@cfworker/json-schema@4.1.1)(supports-color@10.1.0)(zod@4.6.7)':
dependencies:
'@hono/node-server': 2.1.7(hono@4.13.18)
@@ -14764,6 +14825,8 @@ snapshots:
pkce-challenge@5.0.1: {}
+ playwright-core@1.65.1: {}
+
pngjs@7.0.0: {}
portable-executable-signature@2.0.6: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 186ff9edb7..51d7f42ef8 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -56,6 +56,9 @@ catalog:
"@cloudflare/vitest-plugin": 1.4.12
"@cloudflare/workers-oauth-provider": ^0.10.3
"@cloudflare/workers-types": ^4.20260405.1
+ "@modelcontextprotocol/client": 2.4.0
+ "@modelcontextprotocol/core": 2.4.0
+ "@modelcontextprotocol/ext-apps": 2.0.4
"@modelcontextprotocol/sdk": 1.32.2
"@modelcontextprotocol/server": 2.4.0
"@radix-ui/react-accordion": ^1.2.20
@@ -94,6 +97,7 @@ catalog:
miniflare: 5.20261101.0-beta
msw: ^2.15.0
open: ^10.1.2
+ playwright-core: 1.65.1
oxfmt: 0.78.0
oxlint: 1.93.0
react: ^19.2.8
diff --git a/scripts/oxc-config.test.mjs b/scripts/oxc-config.test.mjs
index 5fdf2c270b..a8d36d873e 100644
--- a/scripts/oxc-config.test.mjs
+++ b/scripts/oxc-config.test.mjs
@@ -1,6 +1,9 @@
import assert from "node:assert/strict";
-import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
import { test } from "node:test";
+import { fileURLToPath } from "node:url";
function readRootJson(path) {
return JSON.parse(
@@ -119,3 +122,25 @@ test("mcp-core and toolkit-core cannot import the CLI", () => {
}
assert.match(scripts.lint, /pnpm run lint:deps/);
});
+
+test("mcp-core cannot import the ext-apps SDK at runtime", () => {
+ const root = fileURLToPath(new URL("..", import.meta.url));
+ const dir = mkdtempSync(join(root, "packages/mcp-core/.lint-fixture-"));
+ try {
+ for (const specifier of [
+ "@modelcontextprotocol/ext-apps",
+ "@modelcontextprotocol/ext-apps/server",
+ ]) {
+ const file = join(dir, "view.ts");
+ writeFileSync(file, `export * from "${specifier}";\n`);
+ const lint = spawnSync("pnpm", ["exec", "oxlint", file], {
+ cwd: root,
+ encoding: "utf8",
+ });
+ assert.notEqual(lint.status, 0, specifier);
+ assert.match(lint.stdout, /no-restricted-imports/, specifier);
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});