Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

feat(mcp): streamable HTTP transport with per-request credentials and a fail-closed gate

Beenu Arorab63a7de69152
diff --git a/services/mcp/src/gate.ts b/services/mcp/src/gate.ts
new file mode 100644
index 000000000..a26e5fe50
--- /dev/null
+++ b/services/mcp/src/gate.ts
@@ -0,0 +1,173 @@
+/**
+ * Ask AiSOC whether a tool call may run, and tell it how it went.
+ *
+ * Depth 9.1 (parity 6.6). Over stdio this server was a child process holding
+ * one operator's own API key, and the only thing a tool call could do was
+ * what that person could already do at the console. Over HTTP it is a shared
+ * process reached by several tenants with credentials of their own, and that
+ * changes who is allowed to decide what:
+ *
+ * - **This process decides nothing.** It forwards the caller's credential to
+ * `POST /api/v1/mcp/tool-calls/authorize` and does what it is told. A
+ * policy cached or recomputed here would be a second authority that can
+ * disagree with the first, and the disagreement would be invisible.
+ * - **The tenant is never sent.** It is derived server-side from the
+ * credential. There is no tenant field in either request body, so there is
+ * nothing for a compromised deployment of this process to set.
+ * - **A refusal is actionable.** `approval_required` carries the id of the
+ * row a human decides, so the agent can say what to do rather than failing
+ * opaquely.
+ *
+ * Failure posture: `authorize` fails **closed**. If the API cannot be
+ * reached, no call runs. That is the opposite of `telemetry.ts`, which fails
+ * open on purpose — telemetry is an observation and must not break a call,
+ * whereas this is the authorization. Two surfaces, two postures, stated here
+ * so neither gets changed to match the other by accident.
+ */
+
+import type { Logger } from "./config.js";
+
+/** What the API answers. Mirrors `McpAuthorizeResponse` in the API service. */
+export interface AuthorizeDecision {
+ call_id: string;
+ outcome: "allow" | "deny" | "approval_required";
+ reason: string;
+ approval_id?: string | null;
+ required_permission?: string;
+}
+
+export interface GateOptions {
+ /** Base URL of the AiSOC API. */
+ aisocUrl: string;
+ /** The *caller's* bearer credential, forwarded verbatim. Never the server's. */
+ bearer: string;
+ timeoutMs: number;
+ userAgent: string;
+ log: Logger;
+}
+
+/** Raised when the gate could not reach a decision. Fails the call. */
+export class GateUnavailableError extends Error {
+ constructor(cause: string) {
+ super(
+ `AiSOC could not authorize this tool call (${cause}). ` +
+ `No tool runs without a decision, so this is a refusal rather than a fallback.`,
+ );
+ this.name = "GateUnavailableError";
+ }
+}
+
+async function postJson(
+ url: string,
+ bearer: string,
+ body: unknown,
+ timeoutMs: number,
+ userAgent: string,
+): Promise<{ status: number; json: unknown }> {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), timeoutMs);
+ try {
+ const res = await fetch(url, {
+ method: "POST",
+ headers: {
+ Authorization: bearer.startsWith("Bearer ") ? bearer : `Bearer ${bearer}`,
+ "Content-Type": "application/json",
+ Accept: "application/json",
+ "User-Agent": userAgent,
+ },
+ body: JSON.stringify(body),
+ signal: controller.signal,
+ });
+ // 204 has no body, and `res.json()` on an empty body throws.
+ const json = res.status === 204 ? null : await res.json().catch(() => null);
+ return { status: res.status, json };
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+/**
+ * Authorize one tool call. Throws {@link GateUnavailableError} rather than
+ * returning a permissive default when the API cannot answer.
+ *
+ * `arguments` travels in full because the approval has to bind to the
+ * specific call — approving "investigate case A" must not authorise
+ * "investigate case B". The API hashes it on arrival and stores only the
+ * digest; the audit row records argument *names* alone.
+ */
+export async function authorizeToolCall(
+ opts: GateOptions,
+ toolName: string,
+ args: unknown,
+): Promise<AuthorizeDecision> {
+ let result: { status: number; json: unknown };
+ try {
+ result = await postJson(
+ `${opts.aisocUrl}/api/v1/mcp/tool-calls/authorize`,
+ opts.bearer,
+ { tool_name: toolName, arguments: isPlainObject(args) ? args : {} },
+ opts.timeoutMs,
+ opts.userAgent,
+ );
+ } catch (err) {
+ throw new GateUnavailableError(String(err));
+ }
+
+ if (result.status === 401 || result.status === 403) {
+ return {
+ call_id: "",
+ outcome: "deny",
+ reason:
+ result.status === 401
+ ? "AiSOC rejected the credential this request presented."
+ : "The presented credential is not allowed to use the MCP surface.",
+ };
+ }
+ if (result.status >= 400 || !isPlainObject(result.json)) {
+ throw new GateUnavailableError(`HTTP ${result.status}`);
+ }
+
+ const decision = result.json as unknown as AuthorizeDecision;
+ if (decision.outcome !== "allow" && decision.outcome !== "deny" && decision.outcome !== "approval_required") {
+ // An outcome this build does not know is not an allow. A newer API
+ // inventing a verdict must not be read as permission by an older client.
+ throw new GateUnavailableError(`unrecognised outcome "${String(decision.outcome)}"`);
+ }
+ return decision;
+}
+
+/**
+ * Report how an authorized call turned out.
+ *
+ * Deliberately fire-and-forget and deliberately *not* fail-closed: the call
+ * has already happened, and refusing to return its result because the second
+ * bookkeeping request failed would punish the user for a logging problem.
+ * The decision row is already written, which is the one that has to exist.
+ */
+export async function completeToolCall(
+ opts: GateOptions,
+ callId: string,
+ outcome: "success" | "error" | "invalid_arguments" | "unknown_tool" | "denied",
+ latencyMs: number,
+ errorKind?: string,
+): Promise<void> {
+ if (!callId) return;
+ try {
+ const res = await postJson(
+ `${opts.aisocUrl}/api/v1/mcp/tool-calls/${encodeURIComponent(callId)}/complete`,
+ opts.bearer,
+ { outcome, latency_ms: Math.max(0, Math.round(latencyMs)), ...(errorKind ? { error_kind: errorKind } : {}) },
+ opts.timeoutMs,
+ opts.userAgent,
+ );
+ if (res.status >= 400) {
+ opts.log.info(`gate: completion for ${callId} returned HTTP ${res.status}`);
+ }
+ } catch (err) {
+ opts.log.info(`gate: completion for ${callId} dropped: ${String(err)}`);
+ }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
diff --git a/services/mcp/src/http.ts b/services/mcp/src/http.ts
new file mode 100644
index 000000000..318aa0a9e
--- /dev/null
+++ b/services/mcp/src/http.ts
@@ -0,0 +1,262 @@
+/**
+ * The MCP server over streamable HTTP.
+ *
+ * Depth 9.1 (parity 6.6). Until this file existed the only transport was
+ * stdio, so the only way to reach these tools was to let an MCP host start
+ * the process as a child with one operator's API key written into the host's
+ * configuration file. Nothing in the repository deployed it and nothing
+ * recorded what it read.
+ *
+ * Three decisions here are security decisions, not plumbing:
+ *
+ * **Stateless, one server per request.**
+ * `sessionIdGenerator: undefined` puts the SDK transport in stateless mode
+ * and a fresh `Server` is built per request, bound to the credential that
+ * request presented. The alternative — a session id minted once and reused —
+ * would let a session outlive the credential that created it, so revoking an
+ * API key would not end the sessions it had opened, and anyone who learned a
+ * session id would inherit its tenant. Sessions are cheap to add later and
+ * expensive to take back.
+ *
+ * **The credential comes from the request, never from the environment.**
+ * `AISOC_API_KEY` configures the *stdio* server. Reading it here would mean
+ * an unauthenticated caller, or a caller whose own key had been revoked,
+ * silently answering with the operator's access to somebody else's tenant.
+ * There is no fallback: a request with no `Authorization` header is 401 and
+ * nothing is built. `scripts/check_mcp_over_http.py` fails if this file ever
+ * names `cfg.apiKey`.
+ *
+ * **Every call is authorized by the API before it runs.** See `./gate.ts`.
+ * This process is not the authority on what a key may do, and it fails
+ * closed when it cannot get an answer.
+ *
+ * Binding: `AISOC_MCP_HTTP_HOST` defaults to `127.0.0.1`, which is the right
+ * default for a transport that did not exist yesterday. The compose service
+ * sets `0.0.0.0` because inside a container that is the only way a sibling
+ * service reaches it, and compose publishes the port on the loopback address
+ * the rest of the stack uses.
+ */
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+import { type Logger, type ServerConfig, packageVersion } from "./config.js";
+import { authorizeToolCall, completeToolCall, type GateOptions } from "./gate.js";
+import { buildServer, type CallHooks } from "./server.js";
+
+/** Where the MCP endpoint lives. Fixed so a client's URL is predictable. */
+export const MCP_PATH = "/mcp";
+
+/** Liveness. Deliberately unauthenticated and deliberately says nothing else. */
+export const HEALTH_PATH = "/healthz";
+
+export interface HttpServerOptions {
+ host: string;
+ port: number;
+ /** Cap on a single JSON-RPC frame. A transport with no bound is a memory DoS. */
+ maxBodyBytes: number;
+}
+
+export function resolveHttpOptions(env: NodeJS.ProcessEnv = process.env): HttpServerOptions {
+ const port = Number.parseInt(env.AISOC_MCP_HTTP_PORT ?? "8096", 10);
+ if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+ throw new Error(`Invalid AISOC_MCP_HTTP_PORT: ${env.AISOC_MCP_HTTP_PORT}`);
+ }
+ const maxBodyBytes = Number.parseInt(env.AISOC_MCP_MAX_BODY_BYTES ?? "1048576", 10);
+ return {
+ host: env.AISOC_MCP_HTTP_HOST?.trim() || "127.0.0.1",
+ port,
+ maxBodyBytes: Number.isFinite(maxBodyBytes) && maxBodyBytes > 0 ? maxBodyBytes : 1_048_576,
+ };
+}
+
+/**
+ * Pull the bearer credential out of a request.
+ *
+ * Returns `undefined` rather than a default. Every caller treats that as 401.
+ */
+export function bearerFrom(headers: IncomingMessage["headers"]): string | undefined {
+ const raw = headers.authorization;
+ if (typeof raw !== "string") return undefined;
+ const trimmed = raw.trim();
+ if (!/^bearer\s+\S/i.test(trimmed)) return undefined;
+ return trimmed;
+}
+
+/** Read a bounded JSON body. Rejects rather than truncating. */
+export async function readJsonBody(req: IncomingMessage, maxBytes: number): Promise<unknown> {
+ const chunks: Buffer[] = [];
+ let size = 0;
+ for await (const chunk of req) {
+ const buf = chunk as Buffer;
+ size += buf.length;
+ if (size > maxBytes) {
+ // Truncating would hand the parser a prefix of a frame, which either
+ // fails confusingly or — worse — parses into a different call.
+ throw new Error(`request body exceeds ${maxBytes} bytes`);
+ }
+ chunks.push(buf);
+ }
+ if (size === 0) return undefined;
+ return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+function writeJson(res: ServerResponse, status: number, body: unknown): void {
+ const payload = JSON.stringify(body);
+ res.writeHead(status, { "Content-Type": "application/json", "Content-Length": Buffer.byteLength(payload) });
+ res.end(payload);
+}
+
+/**
+ * The JSON-RPC error a transport-level refusal has to look like.
+ *
+ * An MCP client parses the body before it looks at the status, so a bare
+ * `401 Unauthorized` with an HTML body surfaces in the host as a parse
+ * failure and the operator is told the server is broken rather than that
+ * their credential is missing.
+ */
+function rpcError(res: ServerResponse, status: number, message: string): void {
+ writeJson(res, status, {
+ jsonrpc: "2.0",
+ error: { code: -32001, message },
+ id: null,
+ });
+}
+
+/**
+ * Hooks that put every tool call through the API's authorize/complete pair.
+ *
+ * Built per request so the credential cannot be shared between two callers.
+ */
+export function gateHooks(opts: GateOptions): CallHooks {
+ return {
+ async before(toolName, args) {
+ const decision = await authorizeToolCall(opts, toolName, args);
+ return {
+ allowed: decision.outcome === "allow",
+ reason:
+ decision.outcome === "approval_required"
+ ? `${decision.reason} Ask an approver to decide it, then call the tool again.`
+ : decision.reason,
+ callId: decision.call_id || undefined,
+ };
+ },
+ after(callId, outcome, latencyMs, errorKind) {
+ // Not awaited: the result is already on its way to the agent and a
+ // bookkeeping request must not hold it. Errors are swallowed inside
+ // `completeToolCall`, which logs them.
+ void completeToolCall(opts, callId ?? "", outcome, latencyMs, errorKind);
+ },
+ };
+}
+
+/**
+ * Handle one MCP request end to end.
+ *
+ * Exported so tests can drive it with a fake request/response pair rather
+ * than binding a port.
+ */
+export async function handleMcpRequest(
+ cfg: ServerConfig,
+ log: Logger,
+ options: HttpServerOptions,
+ req: IncomingMessage,
+ res: ServerResponse,
+): Promise<void> {
+ const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+ if (url.pathname === HEALTH_PATH) {
+ writeJson(res, 200, { status: "ok", version: packageVersion(), transport: "streamable-http" });
+ return;
+ }
+ if (url.pathname !== MCP_PATH) {
+ rpcError(res, 404, `Not found. The MCP endpoint is ${MCP_PATH}.`);
+ return;
+ }
+
+ const bearer = bearerFrom(req.headers);
+ if (!bearer) {
+ // No environment fallback, deliberately. See the module header.
+ rpcError(
+ res,
+ 401,
+ "Authorization required. Send `Authorization: Bearer <aisoc_... or JWT>`; " +
+ "the tenant is derived from the credential and cannot be supplied any other way.",
+ );
+ return;
+ }
+
+ let body: unknown;
+ try {
+ body = req.method === "POST" ? await readJsonBody(req, options.maxBodyBytes) : undefined;
+ } catch (err) {
+ rpcError(res, 413, String(err instanceof Error ? err.message : err));
+ return;
+ }
+
+ const gate: GateOptions = {
+ aisocUrl: cfg.aisocUrl,
+ bearer,
+ timeoutMs: cfg.timeoutMs,
+ userAgent: cfg.userAgent,
+ log,
+ };
+
+ // A per-request config carrying the caller's credential. The process-wide
+ // `cfg.apiKey` is not read here and must not be: the whole point of the
+ // HTTP transport is that the caller's own credential decides the tenant.
+ const requestCfg: ServerConfig = { ...cfg, apiKey: bearer.replace(/^Bearer\s+/i, "") };
+
+ const transport = new StreamableHTTPServerTransport({
+ // Stateless. See the module header for why a session id would be worse.
+ sessionIdGenerator: undefined,
+ enableJsonResponse: true,
+ });
+ const server = buildServer(requestCfg, log, gateHooks(gate));
+
+ res.on("close", () => {
+ void transport.close();
+ void server.close();
+ });
+
+ try {
+ await server.connect(transport);
+ await transport.handleRequest(req, res, body);
+ } catch (err) {
+ log.error("mcp http request failed", err);
+ if (!res.headersSent) {
+ rpcError(res, 500, "The MCP server failed to handle this request.");
+ }
+ }
+}
+
+/** Boot the HTTP transport. Resolves when the listener closes. */
+export async function runHttpServer(cfg: ServerConfig, log: Logger): Promise<void> {
+ const options = resolveHttpOptions();
+ const httpServer = createServer((req, res) => {
+ void handleMcpRequest(cfg, log, options, req, res);
+ });
+
+ await new Promise<void>((resolve, reject) => {
+ httpServer.once("error", reject);
+ httpServer.listen(options.port, options.host, () => {
+ httpServer.removeListener("error", reject);
+ resolve();
+ });
+ });
+ // stderr, not stdout: the stdio transport owns stdout and this binary can
+ // be started either way.
+ console.error(
+ `[aisoc-mcp] ${packageVersion()} listening on http://${options.host}:${options.port}${MCP_PATH} (target ${cfg.aisocUrl})`,
+ );
+
+ await new Promise<void>((resolve) => {
+ const shutdown = (sig: string) => {
+ console.error(`[aisoc-mcp] received ${sig}, closing listener`);
+ httpServer.close(() => resolve());
+ };
+ process.once("SIGINT", () => shutdown("SIGINT"));
+ process.once("SIGTERM", () => shutdown("SIGTERM"));
+ httpServer.once("close", () => resolve());
+ });
+}
diff --git a/services/mcp/src/index.ts b/services/mcp/src/index.ts
index 987642d4a..4645149c9 100644
--- a/services/mcp/src/index.ts
+++ b/services/mcp/src/index.ts
@@ -21,6 +21,7 @@ import process from "node:process";
import { type ParsedArgs, parseArgs, packageVersion, resolveConfig, makeLogger } from "./config.js";
import { runDoctor, printDoctorReport } from "./doctor.js";
+import { runHttpServer } from "./http.js";
import { runServer } from "./server.js";
import {
install,
@@ -70,6 +71,16 @@ async function main(): Promise<void> {
async function cmdServe(args: ParsedArgs): Promise<void> {
const cfg = resolveConfig(args);
const log = makeLogger(cfg);
+ // Depth 9.1. `--http` (or AISOC_MCP_HTTP=1) serves streamable HTTP instead
+ // of stdio. Opt-in rather than inferred from the environment: an MCP host
+ // launching this binary as a child process must keep getting stdio, and a
+ // transport that switched itself based on a variable being set somewhere
+ // would be a very hard failure to read from inside Claude Desktop.
+ const wantHttp = args.flags.http === true || args.flags.http === "1" || process.env.AISOC_MCP_HTTP === "1";
+ if (wantHttp) {
+ await runHttpServer(cfg, log);
+ return;
+ }
// No banner on stdout — that channel is reserved for JSON-RPC frames.
// `runServer` logs its lifecycle to stderr.
await runServer(cfg, log);
@@ -205,6 +216,13 @@ function printHelp(): void {
" --timeout <ms> Per-request timeout. Env: AISOC_TIMEOUT_MS. Default 20000.",
" --verbose Log lifecycle events to stderr.",
"",
+ "Serve options:",
+ " --http Serve streamable HTTP instead of stdio. Env: AISOC_MCP_HTTP=1.",
+ " Each request authenticates with its own bearer credential;",
+ " --api-key is not consulted and the tenant comes from the",
+ " credential. Host/port: AISOC_MCP_HTTP_HOST (127.0.0.1),",
+ " AISOC_MCP_HTTP_PORT (8096). Endpoint: /mcp, liveness /healthz.",
+ "",
"Install options:",
" --host <h> claude | cursor | continue | cody",
" --launcher <l> auto (default) | node | npx. `auto` writes a direct",
diff --git a/services/mcp/src/server.ts b/services/mcp/src/server.ts
index 792fbeb32..aff09f1eb 100644
--- a/services/mcp/src/server.ts
+++ b/services/mcp/src/server.ts
@@ -58,13 +58,37 @@ through this MCP server. Typical workflows:
Every agent decision in AiSOC is logged to a persistent ledger; \
\`aisoc_replay_decision\` and \`aisoc_explain_step\` are the auditable surface.`;
+/**
+ * A decision taken before a tool runs, and the report after it.
+ *
+ * Over stdio there is nothing to decide: the server holds the operator's own
+ * key and a tool call can do only what that person could already do. Over
+ * HTTP the credential arrives per request and several tenants share the
+ * process, so `src/http.ts` supplies these two and the API decides. Optional
+ * here so the stdio path is byte-for-byte the behaviour it always had.
+ */
+export interface CallHooks {
+ /**
+ * Called before dispatch. Returning `{ allowed: false }` refuses the call
+ * with `reason` surfaced to the agent, and the tool never runs.
+ */
+ before(toolName: string, args: unknown): Promise<{ allowed: boolean; reason?: string; callId?: string }>;
+ /** Called on every exit path, including the refusals. */
+ after(
+ callId: string | undefined,
+ outcome: "success" | "error" | "invalid_arguments" | "unknown_tool" | "denied",
+ latencyMs: number,
+ errorKind?: string,
+ ): void;
+}
+
/**
* Build (but don't start) an MCP server bound to the AiSOC tool registry.
*
* Exported separately from the start helper so tests can drive request
* handlers without spinning up a real stdio transport.
*/
-export function buildServer(cfg: ServerConfig, log: Logger): Server {
+export function buildServer(cfg: ServerConfig, log: Logger, hooks?: CallHooks): Server {
const client = new AisocClient(cfg, log);
// This server is a standing read path into a customer's alerts, cases and
// event lake, and until now nothing recorded what it read. Off unless
@@ -110,6 +134,7 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {
outcome: "unknown_tool",
latency_ms: Date.now() - startedAt,
});
+ hooks?.after(undefined, "unknown_tool", Date.now() - startedAt);
// Unknown tool. Return as a tool-failure rather than throwing so the
// agent gets a clear human message instead of a transport error.
return toErrorResult(
@@ -117,6 +142,42 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {
);
}
+ // Authorization, when a transport supplied one. Before validation on
+ // purpose: a call that is not allowed must not have its arguments
+ // inspected and reported on, and the refusal has to be recorded whether
+ // or not the arguments were well-formed.
+ let callId: string | undefined;
+ if (hooks) {
+ let verdict: { allowed: boolean; reason?: string; callId?: string };
+ try {
+ verdict = await hooks.before(name, request.params.arguments);
+ } catch (err) {
+ // Fail closed. The gate module raises when it could not reach a
+ // decision, and "could not decide" is not "allowed".
+ log.error(`authorization failed for ${name}`, err);
+ telemetry.record({
+ tool_name: name,
+ argument_keys: keys,
+ outcome: "error",
+ latency_ms: Date.now() - startedAt,
+ error_kind: err instanceof Error ? err.constructor.name : "unknown",
+ });
+ return toErrorResult(err instanceof Error ? err.message : String(err));
+ }
+ callId = verdict.callId;
+ if (!verdict.allowed) {
+ telemetry.record({
+ tool_name: name,
+ argument_keys: keys,
+ outcome: "error",
+ latency_ms: Date.now() - startedAt,
+ error_kind: "NotAuthorized",
+ });
+ hooks.after(callId, "denied", Date.now() - startedAt);
+ return toErrorResult(verdict.reason ?? `${name} is not permitted for this credential.`);
+ }
+ }
+
// Validate via zod. Failed validation gives precise per-field issues.
const parse = tool.schema.safeParse(request.params.arguments ?? {});
if (!parse.success) {
@@ -129,6 +190,7 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {
outcome: "invalid_arguments",
latency_ms: Date.now() - startedAt,
});
+ hooks?.after(callId, "invalid_arguments", Date.now() - startedAt);
return toErrorResult(
formatErrorForTool(new InvalidArgumentsError(name, issues)),
);
@@ -142,6 +204,7 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {
outcome: "success",
latency_ms: Date.now() - startedAt,
});
+ hooks?.after(callId, "success", Date.now() - startedAt);
return toSuccessResult(result);
} catch (err) {
telemetry.record({
@@ -151,6 +214,12 @@ export function buildServer(cfg: ServerConfig, log: Logger): Server {
latency_ms: Date.now() - startedAt,
error_kind: err instanceof Error ? err.constructor.name : "unknown",
});
+ hooks?.after(
+ callId,
+ "error",
+ Date.now() - startedAt,
+ err instanceof Error ? err.constructor.name : "unknown",
+ );
// Log full error to stderr for debugging; surface a sanitised message
// to the agent. We deliberately don't include stack traces in the
// MCP response (PII / secrets risk).