fix: Redact config error details in HTTP transport (#783)

`ConfigurationError`, `LLMProviderError`, and `APICallError` 4xx
currently show
detailed config guidance to all users and are never reported to Sentry.
This is
correct for STDIO (the user can fix their own config), but wrong for the
hosted
Cloudflare deployment where users can't fix server-side config and
operators get
no visibility into these failures.

This adds a `transport` field to `ServerContext` (`"stdio" | "http"`)
and makes
`formatErrorForUser` transport-aware. In HTTP mode, config/provider
errors are
now logged to Sentry via `logIssue()` and a generic "Feature
Unavailable"
message is returned. In STDIO mode (and when transport is unset), the
existing
detailed messages are preserved unchanged.

The transport branching uses a single `formatServerConfigError()` helper
that
takes the detailed message parts and returns the correct response
directly for
both transports.

`UserInputError` always shows details regardless of transport since the
user can
fix their own input in both modes.

Fixes #781

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: dcramer

packages/mcp-cloudflare/src/server/lib/mcp-handler.ts

@@ -173,6 +173,7 @@ const mcpHandler: ExportedHandler<Env> = {
       mcpUrl: env.MCP_URL,
       agentMode: isAgentMode,
       experimentalMode: isExperimentalMode,
+      transport: "http",
     };
 
     // Create and configure MCP server with tools filtered by context

packages/mcp-core/src/internal/error-handling.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { formatErrorForUser } from "./error-handling";
+import {
+  UserInputError,
+  ConfigurationError,
+  LLMProviderError,
+} from "../errors";
+import { APICallError } from "ai";
+
+vi.mock("../telem/logging", () => ({
+  logIssue: vi.fn(() => "mock-event-id"),
+}));
+
+import { logIssue } from "../telem/logging";
+
+describe("formatErrorForUser", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("ConfigurationError", () => {
+    const error = new ConfigurationError("OPENAI_API_KEY is not set");
+
+    it("returns detailed message for stdio transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "stdio" });
+      expect(result).toContain("OPENAI_API_KEY is not set");
+      expect(result).toContain("**Configuration Error**");
+      expect(result).not.toContain("Feature Unavailable");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+
+    it("returns generic message for http transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "http" });
+      expect(result).toContain("**Feature Unavailable**");
+      expect(result).not.toContain("OPENAI_API_KEY is not set");
+      expect(logIssue).toHaveBeenCalledWith(error);
+    });
+
+    it("returns detailed message when transport is undefined (backward compat)", async () => {
+      const result = await formatErrorForUser(error);
+      expect(result).toContain("OPENAI_API_KEY is not set");
+      expect(result).toContain("**Configuration Error**");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("LLMProviderError", () => {
+    const error = new LLMProviderError("Region not supported by OpenAI");
+
+    it("returns detailed message for stdio transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "stdio" });
+      expect(result).toContain("Region not supported by OpenAI");
+      expect(result).toContain("**AI Provider Error**");
+      expect(result).not.toContain("Feature Unavailable");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+
+    it("returns generic message for http transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "http" });
+      expect(result).toContain("**Feature Unavailable**");
+      expect(result).not.toContain("Region not supported by OpenAI");
+      expect(logIssue).toHaveBeenCalledWith(error);
+    });
+
+    it("returns detailed message when transport is undefined", async () => {
+      const result = await formatErrorForUser(error);
+      expect(result).toContain("Region not supported by OpenAI");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("APICallError 4xx", () => {
+    const error = new APICallError({
+      message: "Invalid API key provided",
+      url: "https://api.openai.com/v1/chat/completions",
+      requestBodyValues: {},
+      statusCode: 401,
+      isRetryable: false,
+    });
+
+    it("returns detailed message for stdio transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "stdio" });
+      expect(result).toContain("Invalid API key provided");
+      expect(result).toContain("**AI Provider Error**");
+      expect(result).not.toContain("Feature Unavailable");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+
+    it("returns generic message for http transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "http" });
+      expect(result).toContain("**Feature Unavailable**");
+      expect(result).not.toContain("Invalid API key provided");
+      expect(logIssue).toHaveBeenCalledWith(error);
+    });
+
+    it("returns detailed message when transport is undefined", async () => {
+      const result = await formatErrorForUser(error);
+      expect(result).toContain("Invalid API key provided");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("UserInputError", () => {
+    const error = new UserInputError("Invalid issue ID format");
+
+    it("returns detailed message for http transport (user can fix input)", async () => {
+      const result = await formatErrorForUser(error, { transport: "http" });
+      expect(result).toContain("Invalid issue ID format");
+      expect(result).toContain("**Input Error**");
+      expect(result).not.toContain("Feature Unavailable");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+
+    it("returns detailed message for stdio transport", async () => {
+      const result = await formatErrorForUser(error, { transport: "stdio" });
+      expect(result).toContain("Invalid issue ID format");
+      expect(result).toContain("**Input Error**");
+      expect(logIssue).not.toHaveBeenCalled();
+    });
+  });
+});

packages/mcp-core/src/internal/error-handling.ts

@@ -6,6 +6,7 @@ import {
 import { ApiError, ApiClientError, ApiServerError } from "../api-client";
 import { logIssue } from "../telem/logging";
 import { APICallError } from "ai";
+import type { TransportType } from "../types";
 
 /**
  * Type guard to identify user input validation errors.
@@ -58,56 +59,101 @@ export function isAPICallError(error: unknown): error is APICallError {
   return APICallError.isInstance(error);
 }
 
+const GENERIC_CONFIG_ERROR_MESSAGE = [
+  "**Feature Unavailable**",
+  "This feature is temporarily unavailable due to a server configuration issue.",
+  "The service operator has been notified. Please try again later.",
+].join("\n\n");
+
+/**
+ * Format a server-side configuration error for user display.
+ *
+ * For HTTP transport, the detailed message is hidden (the user cannot fix
+ * server-side configuration) — the error is logged to Sentry and a generic
+ * message is returned instead.
+ * For stdio/unset transport, the detailed parts are returned as-is.
+ */
+function formatServerConfigError(
+  error: Error,
+  detailedParts: string[],
+  options?: { transport?: TransportType },
+): string {
+  if (options?.transport === "http") {
+    logIssue(error);
+    return GENERIC_CONFIG_ERROR_MESSAGE;
+  }
+  return detailedParts.join("\n\n");
+}
+
 /**
  * Format an error for user display with markdown formatting.
  * This is used by tool handlers to format errors for MCP responses.
  *
+ * When transport is "http", config/provider errors are logged to Sentry
+ * and a generic message is returned (users can't fix server-side config).
+ * When transport is "stdio" or undefined, detailed messages are returned
+ * (users can fix their own config).
+ *
  * SECURITY: Only return trusted error messages to prevent prompt injection vulnerabilities.
  * We trust: Sentry API errors, our own UserInputError/ConfigurationError messages, and system templates.
  */
-export async function formatErrorForUser(error: unknown): Promise<string> {
+export async function formatErrorForUser(
+  error: unknown,
+  options?: { transport?: TransportType },
+): Promise<string> {
   if (isUserInputError(error)) {
     return [
       "**Input Error**",
       "It looks like there was a problem with the input you provided.",
       error.message,
-      `You may be able to resolve the issue by addressing the concern and trying again.`,
+      "You may be able to resolve the issue by addressing the concern and trying again.",
     ].join("\n\n");
   }
 
   if (isConfigurationError(error)) {
-    return [
-      "**Configuration Error**",
-      "There appears to be a configuration issue with your setup.",
-      error.message,
-      `Please check your environment configuration and try again.`,
-    ].join("\n\n");
+    return formatServerConfigError(
+      error,
+      [
+        "**Configuration Error**",
+        "There appears to be a configuration issue with your setup.",
+        error.message,
+        "Please check your environment configuration and try again.",
+      ],
+      options,
+    );
   }
 
   if (isLLMProviderError(error)) {
-    return [
-      "**AI Provider Error**",
-      "The AI provider service is not available for this request.",
-      error.message,
-      `This is a service availability issue that cannot be resolved by retrying.`,
-    ].join("\n\n");
+    return formatServerConfigError(
+      error,
+      [
+        "**AI Provider Error**",
+        "The AI provider service is not available for this request.",
+        error.message,
+        "This is a service availability issue that cannot be resolved by retrying.",
+      ],
+      options,
+    );
   }
 
-  // Handle AI SDK APICallError that wasn't converted to LLMProviderError
-  // This is a defensive layer - ideally callEmbeddedAgent converts these
+  // Handle AI SDK APICallError that wasn't converted to LLMProviderError.
+  // This is a defensive layer - ideally callEmbeddedAgent converts these.
   if (isAPICallError(error)) {
     const statusCode = error.statusCode;
     // 4xx errors are user-facing (account issues, rate limits, invalid keys)
-    // These should NOT be logged to Sentry
     if (statusCode && statusCode >= 400 && statusCode < 500) {
-      return [
-        "**AI Provider Error**",
-        "The AI provider service returned an error.",
-        error.message,
-        "This may be a configuration or account issue. Please check your AI provider settings.",
-      ].join("\n\n");
+      return formatServerConfigError(
+        error,
+        [
+          "**AI Provider Error**",
+          "The AI provider service returned an error.",
+          error.message,
+          "This may be a configuration or account issue. Please check your AI provider settings.",
+        ],
+        options,
+      );
     }
-    // 5xx errors - log to Sentry
+    // 5xx errors - always log to Sentry regardless of transport
     const eventId = logIssue(error);
     const parts = [
       "**AI Provider Error**",
@@ -131,7 +177,7 @@ export async function formatErrorForUser(error: unknown): Promise<string> {
       "**Input Error**",
       statusText,
       error.toUserMessage(),
-      `You may be able to resolve the issue by addressing the concern and trying again.`,
+      "You may be able to resolve the issue by addressing the concern and trying again.",
     ].join("\n\n");
   }
 
@@ -142,11 +188,11 @@ export async function formatErrorForUser(error: unknown): Promise<string> {
       ? `There was an HTTP ${error.status} server error with the Sentry API.`
       : "There was a server error.";
 
-    const parts = ["**Error**", statusText, `${error.message}`];
+    const parts = ["**Error**", statusText, error.message];
     if (eventId) {
       parts.push(`**Event ID**: ${eventId}`);
     }
-    parts.push(`Please contact support if the problem persists.`);
+    parts.push("Please contact support if the problem persists.");
     return parts.join("\n\n");
   }
 
@@ -159,8 +205,8 @@ export async function formatErrorForUser(error: unknown): Promise<string> {
     return [
       "**Error**",
       statusText,
-      `${error.message}`,
-      `You may be able to resolve the issue by addressing the concern and trying again.`,
+      error.message,
+      "You may be able to resolve the issue by addressing the concern and trying again.",
     ].join("\n\n");
   }
 

packages/mcp-core/src/server.ts

@@ -373,7 +373,9 @@ function configureServer({
             content: [
               {
                 type: "text" as const,
-                text: await formatErrorForUser(error),
+                text: await formatErrorForUser(error, {
+                  transport: context.transport,
+                }),
               },
             ],
             isError: true,

packages/mcp-core/src/types.ts

@@ -38,6 +38,8 @@ export const CONSTRAINT_PARAMETER_KEYS = new Set<string>([
   "regionUrl",
 ]);
 
+export type TransportType = "stdio" | "http";
+
 export type ServerContext = {
   sentryHost?: string;
   mcpUrl?: string;
@@ -53,4 +55,6 @@ export type ServerContext = {
   agentMode?: boolean;
   /** Whether experimental tools are enabled */
   experimentalMode?: boolean;
+  /** Transport type - affects error message formatting */
+  transport?: TransportType;
 };

packages/mcp-server/src/index.ts

@@ -284,6 +284,7 @@ const context = {
   openaiBaseUrl: cfg.openaiBaseUrl,
   agentMode: cli.agent,
   experimentalMode: cli.experimental,
+  transport: "stdio" as const,
 };
 
 // Build server with context to filter tools based on granted skills