From 1d5bdd531f5dda0b30f0ab86e324b2e075a52491 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 05:34:54 +0000 Subject: [PATCH] fix(mcp): keep caller errors out of Sentry and tag what remains Every tool failure that was not a track_container rejection reached Sentry, so an invalid key, a 404 and an SDK input check each raised an exception event. They all carried one fixed message and stack, so Sentry also merged unrelated failures (MCP-SERVER-F held both ValidationError and NotFoundError). A tool failure now stays out of Sentry when the caller can fix it: a ContainerCheckDigitError, TrackContainerError or ToolInputError from any tool, or a Terminal49 answer of 400, 403, 404, 409, 410 or 422. A 401 counts only for a credential the caller supplied (api_key, agent). The gateway resolves user credentials and configures the shared token itself, so a 401 for those is a gateway/API disagreement and is still reported. The client response and the mcp.tool.error log line are unchanged. Reported failures keep the fixed message and now carry error.class, upstream.status_code, mcp.tool and mcp.credential_type tags, with a fingerprint of class and status. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01V8cPhjxmTweWGCzzfxM9ys --- packages/mcp/src/mcp.test.ts | 7 +- packages/mcp/src/sentry.test.ts | 57 ++++++- packages/mcp/src/sentry.ts | 46 +++++- packages/mcp/src/server.ts | 52 ++++++- packages/mcp/src/tracking-protocol.test.ts | 170 ++++++++++++++------- 5 files changed, 271 insertions(+), 61 deletions(-) diff --git a/packages/mcp/src/mcp.test.ts b/packages/mcp/src/mcp.test.ts index aca8629f..77abe85d 100644 --- a/packages/mcp/src/mcp.test.ts +++ b/packages/mcp/src/mcp.test.ts @@ -844,7 +844,12 @@ describe('MCP server wiring', () => { const result = await searchTool.handler({ query: 'CAIU1234567' }); expect(result.isError).toBe(true); - expect(Sentry.captureException).toHaveBeenCalledWith(expect.any(Error)); + expect(Sentry.captureException).toHaveBeenCalledWith( + expect.any(Error), + expect.objectContaining({ + tags: expect.objectContaining({ 'mcp.tool': 'search_container' }), + }), + ); const captured = vi.mocked(Sentry.captureException).mock.calls[0]?.[0]; expect(captured).toBeInstanceOf(Error); expect((captured as Error).message).not.toContain('internal.example'); diff --git a/packages/mcp/src/sentry.test.ts b/packages/mcp/src/sentry.test.ts index a348fe9e..224227ad 100644 --- a/packages/mcp/src/sentry.test.ts +++ b/packages/mcp/src/sentry.test.ts @@ -2,7 +2,11 @@ import { createServer, type Server } from 'node:http'; import type { AddressInfo } from 'node:net'; import * as Sentry from '@sentry/node'; import { afterAll, beforeAll, describe, expect, it } from 'vite-plus/test'; -import { buildSentryOptions, scrubSensitiveRequestData } from './sentry.js'; +import { + buildSentryOptions, + captureMcpException, + scrubSensitiveRequestData, +} from './sentry.js'; const SECRET_VALUES = [ 'AUTH-SENTINEL-0000', @@ -206,4 +210,55 @@ describe('Sentry event pipeline', () => { expect(sent).not.toContain(value); } }); + + it('sends a tool failure with its class, status and tool, but not its text', async () => { + sentEnvelopes.length = 0; + const upstream = Object.assign( + new Error( + 'Upstream 503 at https://internal.example/v2?token=secret-token', + ), + { name: 'UpstreamError', status: 503 }, + ); + captureMcpException(upstream, { + tool: 'get_container', + credentialType: 'user', + }); + await Sentry.flush(2000); + + const event = sentEnvelopes + .map((envelope) => JSON.parse(envelope)[1][0][1]) + .find((item) => item.exception); + expect(event.exception.values[0]).toMatchObject({ + type: 'UpstreamError', + value: 'The Terminal49 upstream request could not be completed.', + }); + expect(event.tags).toMatchObject({ + 'error.class': 'UpstreamError', + 'upstream.status_code': '503', + 'mcp.tool': 'get_container', + 'mcp.credential_type': 'user', + }); + expect(event.fingerprint).toEqual(['mcp-error', 'UpstreamError', '503']); + const sent = sentEnvelopes.join('\n'); + expect(sent).not.toContain('internal.example'); + expect(sent).not.toContain('secret-token'); + }); + + it('leaves out a status that is not an HTTP status', async () => { + sentEnvelopes.length = 0; + captureMcpException( + Object.assign(new Error('odd'), { name: 'NetworkError', status: 'x' }), + ); + await Sentry.flush(2000); + + const event = sentEnvelopes + .map((envelope) => JSON.parse(envelope)[1][0][1]) + .find((item) => item.exception); + expect(event.tags).not.toHaveProperty('upstream.status_code'); + expect(event.fingerprint).toEqual([ + 'mcp-error', + 'NetworkError', + 'no-status', + ]); + }); }); diff --git a/packages/mcp/src/sentry.ts b/packages/mcp/src/sentry.ts index 005095af..85e459f4 100644 --- a/packages/mcp/src/sentry.ts +++ b/packages/mcp/src/sentry.ts @@ -166,7 +166,35 @@ export function instrumentMcpServer( }); } -export function captureMcpException(error: unknown): void { +/** Where a reported failure happened. Every value is a fixed identifier. */ +export interface McpExceptionContext { + tool?: string; + credentialType?: string; +} + +function httpStatusOf(error: unknown): number | undefined { + const status = + error && typeof error === 'object' + ? (error as { status?: unknown }).status + : undefined; + return typeof status === 'number' && + Number.isInteger(status) && + status >= 100 && + status <= 599 + ? status + : undefined; +} + +/** + * Reports a failure under a fixed message, so no upstream text, URL or token + * reaches Sentry. The error class, the upstream HTTP status and the tool are + * tags, and the class and status set the fingerprint: every report has the + * same message and stack, so without it Sentry merges unrelated failures. + */ +export function captureMcpException( + error: unknown, + context: McpExceptionContext = {}, +): void { if (Sentry.isInitialized()) { const safeError = new Error( 'The Terminal49 upstream request could not be completed.', @@ -175,7 +203,21 @@ export function captureMcpException(error: unknown): void { safeError.name = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/.test(name) ? name : 'Error'; - Sentry.captureException(safeError); + const status = httpStatusOf(error); + const tags: Record = { 'error.class': safeError.name }; + if (status !== undefined) tags['upstream.status_code'] = String(status); + if (context.tool) tags['mcp.tool'] = context.tool; + if (context.credentialType) { + tags['mcp.credential_type'] = context.credentialType; + } + Sentry.captureException(safeError, { + tags, + fingerprint: [ + 'mcp-error', + safeError.name, + status === undefined ? 'no-status' : String(status), + ], + }); } } diff --git a/packages/mcp/src/server.ts b/packages/mcp/src/server.ts index b6068c8f..4b24f9a4 100644 --- a/packages/mcp/src/server.ts +++ b/packages/mcp/src/server.ts @@ -27,6 +27,7 @@ import { TrackContainerError, } from './tools/track-container.js'; import { executeSearchContainer } from './tools/search-container.js'; +import { httpStatus, ToolInputError } from './tools/soft-results.js'; import { executeGetShipmentDetails, shipmentDetailsSchema, @@ -997,8 +998,50 @@ const CONFIRMED_WRITE_CLAUSE: Record = { const APPROVAL_CHANNELS = 'On a client that can ask the user (form elicitation), the client shows the user the preview and asks them to confirm, and the tool writes only on their yes; never pass confirmation_token there. On any other client, the first call returns the preview with a confirmation_token: show the preview to the user, and call again with the same arguments and the token only after the user approves it in this turn.'; +/** + * Terminal49 answers with these statuses when the caller's input or the + * caller's own credential is at fault: invalid or expired key, no access, no + * such record, invalid input. 408 and 429 are absent on purpose: they are + * about load, not the caller. + */ +const CALLER_ERROR_STATUSES: ReadonlySet = new Set([ + 400, 401, 403, 404, 409, 410, 422, +]); + +/** + * Whether a tool failure is the caller's to fix, and so stays out of Sentry. + * The tool still returns it as a tool error and the operator log records it; + * Sentry is for faults the server can fix. + * + * A 401 counts as the caller's only when the caller supplied the credential + * Terminal49 rejected. The gateway itself resolves a `user` credential (a + * WorkOS grant) and configures a `shared_token`, so a 401 for either means + * the gateway and the API disagree about a credential, which is a fault. + */ +function isCallerError( + error: unknown, + credentialType: McpCredentialType, +): boolean { + if ( + error instanceof ContainerCheckDigitError || + error instanceof TrackContainerError || + error instanceof ToolInputError + ) { + return true; + } + // The SDK's HTTP errors carry the response status; an error with none + // (network, timeout, a bug) never reached a Terminal49 answer. + const status = httpStatus(error); + if (status === undefined || !CALLER_ERROR_STATUSES.has(status)) return false; + if (status === 401) { + return credentialType === 'api_key' || credentialType === 'agent'; + } + return true; +} + function wrapTool( toolName: string, + credentialType: McpCredentialType, handler: (args: TArgs, ctx: ServerContext) => Promise, buildResourceLinks?: (result: unknown, args: TArgs) => ResourceLinkContent[], ): ( @@ -1040,12 +1083,8 @@ function wrapTool( }; } catch (error) { const err = error as Error; - const isExpectedTrackingError = - toolName === 'track_container' && - (error instanceof ContainerCheckDigitError || - error instanceof TrackContainerError); - if (!isExpectedTrackingError) { - captureMcpException(error); + if (!isCallerError(error, credentialType)) { + captureMcpException(error, { tool: toolName, credentialType }); await flushMcpEvents(); } // Log the real error for operators; never echo internal messages (which @@ -1366,6 +1405,7 @@ export function createTerminal49McpServer( // resolve that conditional type while InputArgs is still generic. wrapTool( definition.name, + session.credentialType, (args: StandardSchemaWithJSON.InferOutput, ctx) => handler( args, diff --git a/packages/mcp/src/tracking-protocol.test.ts b/packages/mcp/src/tracking-protocol.test.ts index f73fe042..adc8668b 100644 --- a/packages/mcp/src/tracking-protocol.test.ts +++ b/packages/mcp/src/tracking-protocol.test.ts @@ -14,6 +14,7 @@ import { vi, } from 'vite-plus/test'; import { createTerminal49McpServer } from './server.js'; +import type { McpCredentialType } from './tools/context.js'; import { trackContainerAudit } from './tools/track-container.js'; vi.mock('@sentry/node', () => ({ @@ -105,9 +106,14 @@ function apiCalls(requests: RecordedRequest[]): string[] { .filter((call) => call !== 'GET /v2/me'); } -async function connect(): Promise { +async function connect( + credentialType: McpCredentialType = 'api_key', +): Promise { const handler = createMcpHandler( - () => createTerminal49McpServer('TEST_KEY', 'https://api.test/v2'), + () => + createTerminal49McpServer('TEST_KEY', 'https://api.test/v2', undefined, { + credentialType, + }), { legacy: 'stateless', responseMode: 'json' }, ); const client = new Client( @@ -656,29 +662,106 @@ describe('track_container when the API refuses the tracking request', () => { }); }); -describe('unexpected tool failures still report exceptions', () => { +// whoami reads GET /me and nothing else, so its failure is exactly the API's. +function stubMeStatus(status: number): void { + stubApi({ + 'GET /me': () => + new Response( + JSON.stringify({ message: 'UPSTREAM_INTERNAL_DIAGNOSTIC' }), + { + status, + headers: { 'content-type': 'application/vnd.api+json' }, + }, + ), + }); +} + +async function callOnce( + name: string, + args: Record, + credentialType: McpCredentialType = 'api_key', +): Promise>> { + const client = await connect(credentialType); + try { + return await client.callTool({ name, arguments: args }); + } finally { + await client.close(); + } +} + +const trackOnce = () => callOnce('track_container', { number: 'MSKU4330011' }); + +describe('caller errors stay out of exception reporting', () => { it.each([ - { status: 401, name: 'AuthenticationError' }, - { status: 422, name: 'ValidationError' }, - { status: 500, name: 'UpstreamError' }, - ])('reports an unhandled $name from tracking', async ({ status, name }) => { + { status: 400, credentialType: 'api_key' }, + { status: 401, credentialType: 'api_key' }, + { status: 401, credentialType: 'agent' }, + { status: 403, credentialType: 'user' }, + { status: 404, credentialType: 'user' }, + { status: 422, credentialType: 'api_key' }, + ] as const)( + 'returns a $status to whoami for a $credentialType credential as a tool error only', + async ({ status, credentialType }) => { + stubMeStatus(status); + const result = await callOnce('whoami', {}, credentialType); + + expect(result.isError).toBe(true); + expect(textOf(result)).not.toContain('UPSTREAM_INTERNAL_DIAGNOSTIC'); + expect(Sentry.captureException).not.toHaveBeenCalled(); + expect(Sentry.flush).not.toHaveBeenCalled(); + expect(console.error).toHaveBeenCalledWith( + expect.stringContaining('"event":"mcp.tool.error"'), + ); + }, + ); + + it('does not report a container lookup that finds nothing', async () => { + stubApi({}); + const result = await callOnce('get_container', { + id: '11111111-1111-4111-8111-111111111111', + }); + + expect(result.isError).toBe(true); + expect(Sentry.captureException).not.toHaveBeenCalled(); + }); + + it('does not report a tracking request Terminal49 refuses for its input', async () => { stubApi({ 'GET /search': () => ({ data: [] }), 'POST /tracking_requests/infer_number': () => new Response( JSON.stringify({ message: 'UPSTREAM_INTERNAL_DIAGNOSTIC' }), { - status, + status: 422, headers: { 'content-type': 'application/vnd.api+json' }, }, ), }); - const client = await connect(); - try { - const result = await client.callTool({ - name: 'track_container', - arguments: { number: 'MSKU4330011' }, - }); + const result = await trackOnce(); + + expect(result.isError).toBe(true); + expect(Sentry.captureException).not.toHaveBeenCalled(); + }); +}); + +describe('server faults still report exceptions', () => { + it.each([ + { status: 500, name: 'UpstreamError', credentialType: 'api_key' }, + { status: 503, name: 'UpstreamError', credentialType: 'user' }, + { status: 429, name: 'RateLimitError', credentialType: 'api_key' }, + // The gateway resolved this credential itself, so Terminal49 rejecting + // it is a disagreement between the two, not a bad key from the caller. + { status: 401, name: 'AuthenticationError', credentialType: 'user' }, + { + status: 401, + name: 'AuthenticationError', + credentialType: 'shared_token', + }, + ] as const)( + 'reports a $status to whoami for a $credentialType credential with its status and tool', + async ({ status, name, credentialType }) => { + stubMeStatus(status); + const result = await callOnce('whoami', {}, credentialType); expect(result.isError).toBe(true); expect(textOf(result)).not.toContain('UPSTREAM_INTERNAL_DIAGNOSTIC'); @@ -687,31 +770,21 @@ describe('unexpected tool failures still report exceptions', () => { name, message: 'The Terminal49 upstream request could not be completed.', }), + { + tags: { + 'error.class': name, + 'upstream.status_code': String(status), + 'mcp.tool': 'whoami', + 'mcp.credential_type': credentialType, + }, + fingerprint: ['mcp-error', name, String(status)], + }, ); expect(Sentry.flush).toHaveBeenCalledExactlyOnceWith(2000); - } finally { - await client.close(); - } - }); - - it('reports a NotFoundError from a container lookup', async () => { - stubApi({}); - const client = await connect(); - try { - const result = await client.callTool({ - name: 'get_container', - arguments: { id: '11111111-1111-4111-8111-111111111111' }, - }); - - expect(result.isError).toBe(true); - expect(Sentry.captureException).toHaveBeenCalledExactlyOnceWith( - expect.objectContaining({ name: 'NotFoundError' }), - ); - expect(Sentry.flush).toHaveBeenCalledExactlyOnceWith(2000); - } finally { - await client.close(); - } - }); + }, + // A 429 and a 5xx are retried with backoff before they surface. + 20_000, + ); it.each(['TimeoutError', 'TrackContainerError', 'ContainerCheckDigitError'])( 'reports an SDK error named %s without treating its name as a validation class', @@ -727,21 +800,16 @@ describe('unexpected tool failures still report exceptions', () => { throw error; }, }); - const client = await connect(); - try { - const result = await client.callTool({ - name: 'track_container', - arguments: { number: 'MSKU4330011' }, - }); + const result = await trackOnce(); - expect(result.isError).toBe(true); - expect(Sentry.captureException).toHaveBeenCalledExactlyOnceWith( - expect.objectContaining({ name }), - ); - expect(Sentry.flush).toHaveBeenCalledExactlyOnceWith(2000); - } finally { - await client.close(); - } + expect(result.isError).toBe(true); + expect(Sentry.captureException).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ name }), + expect.objectContaining({ + fingerprint: ['mcp-error', name, 'no-status'], + }), + ); + expect(Sentry.flush).toHaveBeenCalledExactlyOnceWith(2000); }, ); });