fix(mcp): relay upstream JSON-RPC error bodies through clerk mcp run

.changeset/mcp-run-relay-error-bodies.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+`clerk mcp run` now relays a structured JSON-RPC error from the upstream server verbatim instead of collapsing it into a generic -32000 error, so a client can see reserved codes like `HeaderMismatch` (-32020) and `UnsupportedProtocolVersion` (-32022) and drive the 2026-07-28 negotiation-retry flow.

packages/cli-core/src/commands/mcp/README.md

@@ -182,6 +182,15 @@ once a session id exists, the same status is instead answered per-request as a
 JSON-RPC error (`-32001`, "requires authentication") and the bridge keeps
 running.
 
+Any other non-2xx response is relayed to the client as-is when its body is a
+well-formed JSON-RPC error (`jsonrpc: "2.0"`, an `id`, and an `error.code`) —
+this is what lets the MCP-reserved codes (`-32020` `HeaderMismatch`, `-32021`
+`MissingRequiredClientCapability`, `-32022` `UnsupportedProtocolVersion`) and
+their `data.supported` payload reach the client so it can drive the
+2026-07-28 negotiation-retry flow. A body that isn't valid JSON, or JSON that
+isn't a JSON-RPC error, falls back to a generic `-32000` ("Upstream returned
+HTTP `<status>`.").
+
 ### `clerk mcp uninstall`
 
 Remove the entry. For CLI-registered clients (claude, gemini, codex, openclaw,

packages/cli-core/src/commands/mcp/run.test.ts

@@ -37,9 +37,9 @@ function stub(handler: (req: Recorded, postIndex: number) => Response): void {
   });
 }
 
-function json(payload: unknown, headers: Record<string, string> = {}): Response {
+function json(payload: unknown, headers: Record<string, string> = {}, status = 200): Response {
   return new Response(JSON.stringify(payload), {
-    status: 200,
+    status,
     headers: { "content-type": "application/json", ...headers },
   });
 }
@@ -393,6 +393,120 @@ describe("mcp run (stdio bridge)", () => {
     expect(out.join("")).toBe("");
   });
 
+  test("relays a structured JSON-RPC error body from a 400 upstream verbatim", async () => {
+    const upstreamError = {
+      jsonrpc: "2.0",
+      id: 1,
+      error: {
+        code: -32022,
+        message: "Unsupported protocol version",
+        data: { supported: ["2025-06-18", "2024-11-05"] },
+      },
+    };
+    stub((req) => noServerStream(req) ?? json(upstreamError, {}, 400));
+    const out: string[] = [];
+
+    await mcpRun(
+      { url: URL },
+      { input: lines({ jsonrpc: "2.0", id: 1, method: "tools/list" }), write: (c) => out.push(c) },
+    );
+
+    expect(framesFrom(out)[0]).toEqual(upstreamError);
+  });
+
+  test("keeps a notification silent even when the upstream error body is a JSON-RPC error", async () => {
+    const upstreamError = {
+      jsonrpc: "2.0",
+      id: null,
+      error: { code: -32600, message: "Invalid notification" },
+    };
+    stub((req) => noServerStream(req) ?? json(upstreamError, {}, 400));
+    const out: string[] = [];
+
+    await mcpRun(
+      { url: URL },
+      {
+        input: lines({ jsonrpc: "2.0", method: "notifications/initialized" }),
+        write: (c) => out.push(c),
+      },
+    );
+
+    expect(out.join("")).toBe("");
+  });
+
+  test("answers with a structured -32000 when the upstream error body dies mid-read", async () => {
+    // Error on the second pull, not in start(): erroring at construction
+    // surfaces as a fetch failure before the response is even returned. The
+    // regression under test is a body that dies while being read. Today that
+    // read happens inside loggedFetch's non-ok clone().text() (so its message
+    // wins); relayUpstreamError's own catch covers the same failure if that
+    // pre-read ever moves behind --verbose. Either way the invariant is: one
+    // structured -32000 reply, bridge stays alive.
+    let pulls = 0;
+    const body = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls += 1;
+        if (pulls === 1) {
+          controller.enqueue(new TextEncoder().encode('{"jsonrpc":"2.0","id":1,'));
+          return;
+        }
+        controller.error(new Error("connection reset"));
+      },
+    });
+    stub(
+      (req) =>
+        noServerStream(req) ??
+        new Response(body, { status: 500, headers: { "content-type": "application/json" } }),
+    );
+    const out: string[] = [];
+
+    await mcpRun(
+      { url: URL },
+      { input: lines({ jsonrpc: "2.0", id: 1, method: "tools/list" }), write: (c) => out.push(c) },
+    );
+
+    const frames = framesFrom(out);
+    expect(frames).toHaveLength(1);
+    const error = frames[0]?.error as { code?: number; message?: string } | undefined;
+    expect(error?.code).toBe(-32000);
+    expect(error?.message).toStartWith("Upstream");
+  });
+
+  test("falls back to a generic -32000 when a 500 upstream returns a non-JSON (HTML) body", async () => {
+    stub(
+      (req) =>
+        noServerStream(req) ??
+        new Response("<html><body>Internal Server Error</body></html>", {
+          status: 500,
+          headers: { "content-type": "text/html" },
+        }),
+    );
+    const out: string[] = [];
+
+    await mcpRun(
+      { url: URL },
+      { input: lines({ jsonrpc: "2.0", id: 1, method: "tools/list" }), write: (c) => out.push(c) },
+    );
+
+    const error = framesFrom(out)[0]?.error as { code?: number; message?: string } | undefined;
+    expect(error?.code).toBe(-32000);
+    expect(error?.message).toBe("Upstream returned HTTP 500.");
+  });
+
+  test("falls back to a generic -32000 when a 400 upstream returns JSON that isn't JSON-RPC", async () => {
+    stub((req) => noServerStream(req) ?? json({ ok: false, reason: "bad request" }, {}, 400));
+    const out: string[] = [];
+
+    await mcpRun(
+      { url: URL },
+      { input: lines({ jsonrpc: "2.0", id: 1, method: "tools/list" }), write: (c) => out.push(c) },
+    );
+
+    const error = framesFrom(out)[0]?.error as { code?: number; message?: string } | undefined;
+    expect(error?.code).toBe(-32000);
+    expect(error?.message).toBe("Upstream returned HTTP 400.");
+  });
+
   test("replies with -32000 when an SSE response stream dies before the reply", async () => {
     const body = new ReadableStream<Uint8Array>({
       start(controller) {

packages/cli-core/src/commands/mcp/run.ts

@@ -191,6 +191,13 @@ async function dispatch(message: JSONRPCMessage, ctx: DispatchCtx): Promise<void
   if (response.status === 202 || response.status === 204) return;
 
   if (!response.ok) {
+    // A structured JSON-RPC error body (e.g. the MCP-reserved -32020..-32022
+    // codes with `data.supported`) carries information the driving client
+    // needs — most importantly for the 2026-07-28 negotiation-retry flow.
+    // Relay it verbatim instead of collapsing it into a generic -32000.
+    // Notifications never get a reply, not even a relayed upstream error —
+    // emitError below already stays silent for them.
+    if ("id" in message && (await relayUpstreamError(response, emitPayload))) return;
     await emitError(message, emit, -32000, `Upstream returned HTTP ${response.status}.`);
     return;
   }
@@ -290,6 +297,40 @@ async function emitError(
   await emit({ jsonrpc: "2.0", id: message.id, error: { code, message: text } });
 }
 
+/**
+ * Attempt to relay a non-ok upstream response as-is: read the body, and if it
+ * parses as a well-formed JSON-RPC error, forward it verbatim through the
+ * normal emit path. Returns `false` (nothing emitted) for a non-JSON body or
+ * JSON that isn't a JSON-RPC error, so the caller falls back to a generic
+ * -32000.
+ */
+async function relayUpstreamError(response: Response, emitPayload: Emit): Promise<boolean> {
+  let text: string | undefined;
+  try {
+    text = await readTextCapped(response, MAX_LINE_BYTES);
+  } catch {
+    // A body that dies mid-read is just an unreadable body — fall back rather
+    // than letting the rejection escape and take the whole bridge down.
+    return false;
+  }
+  if (text === undefined || text.trim().length === 0) return false;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return false;
+  }
+  if (!isJsonRpcErrorResponse(parsed)) return false;
+  await emitPayload(parsed);
+  return true;
+}
+
+/** True when a parsed body is a well-formed JSON-RPC 2.0 error response. */
+function isJsonRpcErrorResponse(payload: unknown): boolean {
+  if (!isRecord(payload) || payload.jsonrpc !== "2.0" || !("id" in payload)) return false;
+  return isRecord(payload.error) && typeof payload.error.code === "number";
+}
+
 function requestHeaders(session: Session): Record<string, string> {
   return {
     "Content-Type": "application/json",