Network: modern Mcp-* headers, new error codes, cancellation-as-abort (#1628) (#1722)

* Network: modern Mcp-* headers, new error codes, cancellation-as-abort (#1628)

Upgrade the Network tab for the modern Streamable HTTP transport
(SEP-2243 / SEP-2575):

- Recognise and highlight the mirrored headers (Mcp-Method, Mcp-Name,
  Mcp-Param-*, MCP-Protocol-Version), decode =?base64?…?= sentinel values
  inline, and cross-check each against the request body so a HeaderMismatch
  is visible before the server rejects it.
- Show the new spec error codes distinctly: -32020 HeaderMismatch,
  -32021 MissingRequiredClientCapability, -32022 UnsupportedProtocolVersion
  (with the server-advertised `supported` versions), and modern -32601
  MethodNotFound on HTTP 404 (distinguished from a legacy bare 404 by its
  JSON-RPC body).
- Reflect cancellation as a connection abort ("Cancelled") rather than a
  hard error, per SEP §7.5.
- Confirm and document browser-path header mirroring: the SDK builds the
  Mcp-* headers client-side and the /api/fetch proxy forwards them verbatim
  (new integration test).

New pure util `mcpNetworkHeaders.ts` holds the recognition/decode/classify
logic; new `McpErrorBadge` element renders the distinct error chips. The
optional raw-request controls (cacheMode bypass/refresh, single-page fetch)
are split to #1721 — they are cross-cutting core + feature-tab work beyond
the Network tab.

Also refreshes the AGENTS.md board Status option-ID table (the Building /
MCP Apps Extension columns were removed).

Closes #1628

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network smoke-test showcase + fix redaction clobbering JSON-RPC error codes

Adds a composable "modern-network" showcase server for exercising the #1628
Network-tab work end-to-end, and fixes a real bug the smoke test surfaced.

Bug fix (core): the fetch-tracking body redaction masked ANY field named
`code` (targeting the OAuth authorization code), including the numeric
JSON-RPC `error.code`. That destroyed the field the Network tab classifies
the modern spec errors on, so -32020/-32021/-32022/-32601 never rendered
against real traffic. Redaction now only masks STRING values of a sensitive
field (secrets are always strings; a numeric code is never one).

Test-server showcase (test-servers): `modern-network-http.json` serves a
`get_weather` tool with an `x-mcp-header: "City"` annotation plus four
`trigger_*` tools. A new `transport.modern.injectSpecErrors` flag installs a
middleware on the modern leg that answers the triggers with real HTTP status
+ JSON-RPC error bodies (400/-32020, 400/-32021, 400/-32022 w/ `supported`,
404/-32601), so the Inspector's error rendering can be driven live.

Mirroring finding (verified live, comment corrected in createRemoteFetch.ts):
the SDK builds the STANDARD mirrored headers (Mcp-Method / Mcp-Name /
MCP-Protocol-Version) unconditionally — they reach the server through the
web proxy — but gates `Mcp-Param-*` on a non-browser environment
(`detectProbeEnvironment() !== "browser"`), so the web client never emits
them. An x-mcp-header tool is therefore uncallable from the web client
against a strict modern server (it answers -32020); it works from the Node
CLI/TUI. The earlier "mirroring works through the proxy" note was corrected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network: move the spec-error badge off the crowded compact top row

In the narrow monitoring sidebar (embedded layout) the McpErrorBadge shared
the top row with the timestamp/method/category/duration/status chips, which
truncated the method and category ("PO…", "TRANSP…") and clipped the error
name. Render the badge separately from `metaBadges` and place it on the
second row, to the right of the URL, so the top row stays readable and the
error name shows in full. The full-width layout keeps it in the top-right
cluster (where there's room).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network: keep the spec error name's casing in McpErrorBadge (no uppercase)

The four spec/SDK error identifiers are PascalCase (`HeaderMismatch`,
`MissingRequiredClientCapability`, `UnsupportedProtocolVersion`,
`MethodNotFound`). Mantine's Badge uppercases label text by default, which
flattened them to a hard-to-read run-together string
("UNSUPPORTEDPROTOCOLVERSION"). Set `tt="none"` so the badge shows the
spec's own casing with word boundaries intact; short badges (POST, status)
keep the default uppercase.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network: in the full-width layout, move the spec-error badge to the second row

The full-width entry kept the McpErrorBadge in the top-right cluster, where a
long spec name (e.g. "MissingRequiredClientCapability") crowded the top row
and truncated the method chips and URL. Move it to the start of the second
row (the expand-toggle row) so the top row stays readable; the toggle stays
at the end (`space-between` only when the badge is present). The compact
sidebar already places it on its second row beside the URL.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Protocol: show Replay as the right-side icon in the wide layout too

The compact (sidebar) ProtocolEntry already renders Replay as an icon next to
the pin/expand icons; the wide layout used a left-aligned "Replay" text
button instead. Make the wide layout match — Replay as the ReplayButton icon
at the start of the right-side action cluster (Replay, Pin, Expand) — so the
two layouts are consistent. Drops the now-unused SubtleButton constant.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Move the modern spec-error chip + alert from the Network tab to the Protocol tab

The Network tab is focused on the HTTP transaction; the distinct protocol-error
taxonomy (-32020/-32021/-32022/-32601) belongs with the protocol messages. So:

- ProtocolEntry now renders the McpErrorBadge chip on the top line (right after
  the direction badge, both layouts) plus an explanatory alert in the expanded
  detail, classified by JSON-RPC error code via `classifyProtocolSpecError`.
- NetworkEntry drops the chip + alert; it keeps the HTTP-level features (status
  badge, Mcp-* header highlight/sentinel-decode, header/body mismatch marker,
  cancellation-as-abort).
- The SDK delivers -32020/21/22 (HTTP 400) as JSON-RPC error responses, so they
  reach the Protocol log directly. -32601 (HTTP 404) and other non-enveloped
  errors are *thrown* — the request stays pending. `enrichProtocolEntries`
  (App) correlates the Protocol log to the Network log by JSON-RPC id (parsed
  from the transport fetch's requestBody) and folds the thrown error onto its
  pending request, so it too appears in Protocol. This is a derived view; the
  underlying log is not mutated.

Verified live against the modern-network showcase: both a -32020 error response
and a thrown -32601 render distinctly in the Protocol tab.

Follow-up: a "reveal in Network" link on the Protocol alert (cross-tab
scroll-to + expand of the correlated HTTP entry).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Protocol: show the spec-error chip only in the wide layout, after the method

Refine the placement of the spec-error chip added in the previous commit:
- Wide layout: move it from after the direction badge to right after the
  method chip (reads as "tools/call  -32020 HeaderMismatch").
- Compact sidebar row: drop the chip entirely — the two-line row stays
  uncluttered and relies on its ERROR status badge. The explanatory alert
  still appears in the expanded detail in both layouts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Protocol: "reveal in Network" link — jump from a spec error to its HTTP entry

Adds the cross-tab navigation that was the follow-up to relocating the
spec-error rendering. The expanded Protocol alert now shows a "View the HTTP
request in the Network tab" link when the entry has a correlated Network
request; clicking it:

- correlates the Protocol message to its transport fetch by JSON-RPC id
  (`revealableMessageIds` gates the link; `correlateFetchEntry` finds the
  target on click),
- clears whatever filter would hide the target (network filterText +
  category, and the embedded monitorSearch),
- switches to the Network view in whichever mode is active — the pinned
  column (`pinMonitor`) when the sidebar is open, or the full-screen header
  tab (`onActiveTabChange`) when it's closed,
- scrolls the matching NetworkEntry into view and force-expands it.

The reveal is a one-shot: a new `revealId` threads NetworkScreen →
NetworkStreamPanel → NetworkEntry, where the targeted entry scrolls itself
into view (rAF, after `useScrollMemory`'s restore) + expands, then clears the
signal via `onRevealComplete`. Verified live in both the pinned-sidebar and
closed/full-screen layouts.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Protocol: only show the "reveal in Network" link when it adds value

Gate the link on a new `httpRelevant` flag: show it only when the error is
either thrown by the SDK (its real HTTP response lives only in the Network
log — the Protocol entry is a synthetic fold) OR tied to the HTTP request
headers. A delivered, protocol-only error gets no link, since the raw HTTP
entry adds nothing over the alert.

- -32020 HeaderMismatch  → link (the mirrored headers are the problem)
- -32601 MethodNotFound  → link (thrown; the 404 response is only in Network)
- -32021 MissingRequiredClientCapability → no link (delivered, protocol-only)
- -32022 UnsupportedProtocolVersion      → no link (supported list is in the alert)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network: cite SEP-2575 for cancellation-as-abort, not the internal doc's §7.5

The cancellation note referenced "(SEP §7.5)", but §7.5 is a section of the
internal v2_new_spec_impact.md doc, not a SEP. The behavior — closing the
Streamable HTTP request stream is the cancellation signal; notifications/cancelled
is stdio-only — is defined in SEP-2575 (stateless-mcp). Cite SEP-2575 in the
user-facing alert and the two related comments.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network: fix reveal one-shot canceling its own scroll; review doc/comment nits

Address @claude review of #1722:
- Reveal one-shot: move onRevealComplete() inside the rAF (after scrollIntoView)
  so clearing revealId (which flips revealed->false and runs the effect cleanup)
  can no longer race/cancel the pending scroll. Add a flip-back test.
- Comment the intentional double-mount of revealId (pinned monitor + full-screen
  ScreenStage both match; clear is idempotent).
- Doc drift after the Network->Protocol relocation: McpErrorBadge + the
  mcpNetworkHeaders module header now say the spec-error chip lives in Protocol.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Network: clarify redaction array-of-scalars edge + revealableIds superset

Address second @claude review of #1722 (both non-blocking polish notes):
- fetchTracking redaction: note that masking assumes a sensitive value is a
  scalar or object; an array-of-scalars under a sensitive key would slip through
  (no OAuth/token payload has that shape).
- revealableMessageIds: document it's a superset of the linked entries; the
  spec-error/httpRelevant narrowing is applied downstream at render.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Protocol: gate modern -32601 framing to a genuine 404, not in-band 200

Address third @claude review of #1722. classifyProtocolSpecError recognised
-32601 from the code alone, so an ordinary in-band 'method not found' returned
on HTTP 200 was dressed up as the modern MethodNotFound taxonomy: the spec
badge, a 404-asserting alert, and a 'reveal in Network' link that jumped to a
plain 200 (claiming diagnostic value that wasn't there).

Gate the modern -32601 treatment on the correlated fetch actually being a 404
(mirroring classifyMcpSpecError). -32020/-32021/-32022 are SEP-reserved and
unaffected. The correlated HTTP status is threaded from InspectorView (new
correlatedFetchStatusById) through ProtocolScreen/ProtocolListPanel to
ProtocolEntry; when unknown, -32601 falls back to code-only recognition (the
thrown-404 path always carries a 404). Badge, alert copy, and link now resolve
together, so a plain in-band -32601 falls through to ordinary error rendering.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

* Protocol: require a genuine 404 for modern -32601 (drop unknown-status fallback)

Address fourth @claude review of #1722. The prior fix only rejected -32601 when
the status was *known* and not 404; an unknown status fell back to code-only
recognition. But the thrown-404 path always carries a 404 (folded in from a 404
fetch), so the unknown-status branch is only ever reached by an ordinary in-band
-32601 with no correlated 404 — most notably a stdio connection (no HTTP at all)
— which then wrongly got the modern MethodNotFound badge and 404-asserting copy.

Drop the escape hatch: -32601 is the modern taxonomy only on httpStatus === 404.
Nothing intended is lost (the genuine case always has its 404). Update the tests
(code-only/undefined -32601 now expects null; add a stdio no-correlated-fetch
ProtocolEntry case) and mark the MethodNotFound story with correlatedHttpStatus
404.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

test-servers/configs/modern-network-http.json

@@ -0,0 +1,20 @@
+{
+  "serverInfo": {
+    "name": "modern-network-showcase",
+    "version": "1.0.0"
+  },
+  "tools": [
+    { "preset": "echo" },
+    { "preset": "get_weather" },
+    { "preset": "trigger_header_mismatch" },
+    { "preset": "trigger_missing_capability" },
+    { "preset": "trigger_unsupported_version" },
+    { "preset": "trigger_method_not_found" }
+  ],
+  "resources": [{ "preset": "architecture" }],
+  "transport": {
+    "type": "streamable-http",
+    "port": 3110,
+    "modern": { "legacy": "stateless", "injectSpecErrors": true }
+  }
+}

test-servers/src/composable-test-server.ts

@@ -563,6 +563,14 @@ export interface ServerConfig {
    */
   modern?: {
     legacy?: "stateless" | "reject";
+    /**
+     * When true, the modern HTTP leg installs a middleware that returns the
+     * SEP-2243 / SEP-2575 spec error codes for specially-named trigger tool
+     * calls (see `SPEC_ERROR_TRIGGERS` in test-server-http.ts). Used by the
+     * `modern-network-http` showcase to exercise the Inspector's Network-tab
+     * error rendering (a conformant server never produces these on demand).
+     */
+    injectSpecErrors?: boolean;
   };
   /**
    * Optional server control for orderly shutdown (test HTTP server).

test-servers/src/load-config.ts

@@ -72,7 +72,9 @@ export interface ConfigFile {
      * is shorthand for dual-era stateless serving; the object form selects the
      * legacy-fallback posture. See {@link ServerConfig.modern}.
      */
-    modern?: boolean | { legacy?: "stateless" | "reject" };
+    modern?:
+      | boolean
+      | { legacy?: "stateless" | "reject"; injectSpecErrors?: boolean };
   };
 }
 

test-servers/src/preset-registry.ts

@@ -15,6 +15,8 @@ import {
   createGetEnvTool,
   createAddTool,
   createGetSumTool,
+  createGetWeatherTool,
+  createSpecErrorTriggerTool,
   createWriteToStderrTool,
   createCollectSampleTool,
   createListRootsTool,
@@ -94,6 +96,28 @@ function resolveToolPreset(
       return createAddTool();
     case "get_sum":
       return createGetSumTool();
+    case "get_weather":
+      return createGetWeatherTool();
+    case "trigger_header_mismatch":
+      return createSpecErrorTriggerTool(
+        "trigger_header_mismatch",
+        "Returns -32020 HeaderMismatch (HTTP 400)",
+      );
+    case "trigger_missing_capability":
+      return createSpecErrorTriggerTool(
+        "trigger_missing_capability",
+        "Returns -32021 MissingRequiredClientCapability (HTTP 400)",
+      );
+    case "trigger_unsupported_version":
+      return createSpecErrorTriggerTool(
+        "trigger_unsupported_version",
+        "Returns -32022 UnsupportedProtocolVersion (HTTP 400)",
+      );
+    case "trigger_method_not_found":
+      return createSpecErrorTriggerTool(
+        "trigger_method_not_found",
+        "Returns -32601 MethodNotFound (HTTP 404)",
+      );
     case "write_to_stderr":
       return createWriteToStderrTool();
     case "collect_sample":

test-servers/src/test-server-fixtures.ts

@@ -218,6 +218,49 @@ export function createAddTool(): ToolDefinition {
   };
 }
 
+/**
+ * Create a "get_weather" tool carrying a SEP-2243 `x-mcp-header` annotation on
+ * its `city` argument, so a modern client mirrors the value into a
+ * `Mcp-Param-City` header (Base64-sentinel-encoded when the value is non-ASCII).
+ * Used by the `modern-network-http` showcase to exercise the Network tab's
+ * `Mcp-Param-*` decode.
+ */
+export function createGetWeatherTool(): ToolDefinition {
+  return {
+    name: "get_weather",
+    description:
+      "Get the weather for a city (its `city` argument mirrors to Mcp-Param-City)",
+    inputSchema: {
+      city: z
+        .string()
+        .describe("City name")
+        .meta({ "x-mcp-header": "City" }),
+    },
+    handler: async (params: Record<string, unknown>) => {
+      return toToolResult(`Weather in ${params.city as string}: sunny, 24°C`);
+    },
+  };
+}
+
+/**
+ * Create a no-op "trigger" tool whose `tools/call` is intercepted by the modern
+ * leg's spec-error injector (`injectSpecErrors`) to return a crafted
+ * SEP-2243/SEP-2575 error. The handler is a harmless fallback for the
+ * (never-reached) case where the injector is off.
+ */
+export function createSpecErrorTriggerTool(
+  name: string,
+  description: string,
+): ToolDefinition {
+  return {
+    name,
+    description,
+    inputSchema: {},
+    handler: async () =>
+      toToolResult(`(${name}) injector disabled — no error returned`),
+  };
+}
+
 /**
  * Create a "get_sum" tool that returns the sum of two numbers (alias for add)
  */

test-servers/src/test-server-http.ts

@@ -125,6 +125,67 @@ function extractHeaders(req: Request): Record<string, string> {
   return headers;
 }
 
+/**
+ * Maps a trigger `tools/call` name to the crafted spec-error response the
+ * injector returns (see {@link ServerConfig.modern}.injectSpecErrors). Each is a
+ * real HTTP status + JSON-RPC error body per the 2026-07-28 transport spec, so
+ * the Inspector's Network tab renders the taxonomy exactly as it would from a
+ * real modern server.
+ */
+const SPEC_ERROR_TRIGGERS: Record<
+  string,
+  { httpStatus: number; code: number; message: string; data?: unknown }
+> = {
+  trigger_header_mismatch: {
+    httpStatus: 400,
+    code: -32020,
+    message: "Mcp-Method header does not match the JSON-RPC body",
+  },
+  trigger_missing_capability: {
+    httpStatus: 400,
+    code: -32021,
+    message: "Client is missing a required capability",
+  },
+  trigger_unsupported_version: {
+    httpStatus: 400,
+    code: -32022,
+    message: "Unsupported protocol version",
+    data: { supported: ["2025-06-18", "2025-11-25", "2026-07-28"] },
+  },
+  trigger_method_not_found: {
+    httpStatus: 404,
+    code: -32601,
+    message: "Method not found",
+  },
+};
+
+interface JsonRpcCallBody {
+  id?: string | number | null;
+  method?: string;
+  params?: { name?: string };
+}
+
+const specErrorInjector: express.RequestHandler = (req, res, next) => {
+  const body = req.body as JsonRpcCallBody | undefined;
+  const trigger =
+    body?.method === "tools/call" && typeof body.params?.name === "string"
+      ? SPEC_ERROR_TRIGGERS[body.params.name]
+      : undefined;
+  if (!trigger) {
+    next();
+    return;
+  }
+  res.status(trigger.httpStatus).json({
+    jsonrpc: "2.0",
+    id: body?.id ?? null,
+    error: {
+      code: trigger.code,
+      message: trigger.message,
+      ...(trigger.data !== undefined ? { data: trigger.data } : {}),
+    },
+  });
+};
+
 // With this test server, your test can hold an instance and you can get the server's recorded message history at any time.
 //
 export class TestServerHttp {
@@ -296,7 +357,15 @@ export class TestServerHttp {
       }
     };
 
-    app.post("/mcp", ...mcpMiddleware, route);
+    // Optional spec-error injector: returns the SEP-2243 / SEP-2575 error codes
+    // for the trigger tool calls so the Inspector's Network tab can be exercised
+    // against them (a conformant server never emits these on demand).
+    const extraMiddleware: express.RequestHandler[] = this.config.modern
+      ?.injectSpecErrors
+      ? [specErrorInjector]
+      : [];
+
+    app.post("/mcp", ...mcpMiddleware, ...extraMiddleware, route);
     app.get("/mcp", ...mcpMiddleware, route);
     app.delete("/mcp", ...mcpMiddleware, route);