feat: add --protocol-era launch flag for ad-hoc servers (#2208)

An ad-hoc --server-url / command launch always negotiated the legacy era,
because protocolEra was only settable per server in mcp.json. A wrapper
that mints a short-lived bearer token therefore had to write that token to
disk to exercise a server under auto or modern.

--protocol-era <legacy|auto|modern> now feeds settings.protocolEra in all
three clients through a shared parseProtocolEra coercer:

- CLI/TUI overlay it in loadServerEntries alongside --header, onto an
  ad-hoc target and onto a --catalog/--config entry for that run.
- Web stamps it on the in-memory ad-hoc entry, which the backend lifts
  into settings like headers; as with --header it is rejected alongside
  --catalog/--config, but unlike --header it applies to stdio too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SZ4rrvH6xaCfrst75gJh7x
Signed-off-by: cliffhall <cliff@futurescale.com>

clients/web/server/run-web.ts

@@ -10,12 +10,14 @@ import { Command } from "commander";
 import type {
   MCPConfig,
   MCPServerConfig,
+  ServerProtocolEra,
   StoredMCPServer,
 } from "../../../core/mcp/types.ts";
 import {
   resolveServerConfigs,
   parseKeyValuePair,
   parseHeaderPair,
+  parseProtocolEra,
   type ServerConfigOptions,
 } from "../../../core/mcp/node/config.ts";
 import {
@@ -89,6 +91,11 @@ export async function runWeb(argv: string[]): Promise<number> {
       parseHeaderPair,
       {},
     )
+    .option(
+      "--protocol-era <era>",
+      "protocol era for the ad-hoc server: legacy, auto, or modern (default legacy)",
+      parseProtocolEra,
+    )
     .option("--dev", "run in development mode (Vite)")
     .parse(preArgs);
 
@@ -101,6 +108,7 @@ export async function runWeb(argv: string[]): Promise<number> {
     serverUrl?: string;
     cwd?: string;
     header?: Record<string, string>;
+    protocolEra?: ServerProtocolEra;
     dev?: boolean;
   };
 
@@ -124,6 +132,10 @@ export async function runWeb(argv: string[]): Promise<number> {
   const hasCatalog = !!catalogPath;
   const hasConfig = !!opts.config;
   const hasHeaders = !!opts.header && Object.keys(opts.header).length > 0;
+  // Like `--header`, web applies `--protocol-era` only to an ad-hoc server: a
+  // catalog/config entry carries its own `protocolEra`, editable in Server
+  // Settings, and web never overlays launch flags onto a file's settings.
+  const hasProtocolEra = opts.protocolEra !== undefined;
   const hasAdHocServer =
     target.length > 0 ||
     !!opts.serverUrl ||
@@ -137,11 +149,15 @@ export async function runWeb(argv: string[]): Promise<number> {
         ? "--catalog cannot be combined with an ad-hoc server URL/command."
         : hasCatalog && hasHeaders
           ? "--header cannot be combined with --catalog. Set per-server headers in the catalog file."
-          : hasConfig && hasAdHocServer
-            ? "--config cannot be combined with an ad-hoc server URL/command. --config selects a read-only session file."
-            : hasConfig && hasHeaders
-              ? "--header cannot be combined with --config. Set per-server headers inside the config file instead."
-              : null;
+          : hasCatalog && hasProtocolEra
+            ? "--protocol-era cannot be combined with --catalog. Set protocolEra per server in the catalog file."
+            : hasConfig && hasAdHocServer
+              ? "--config cannot be combined with an ad-hoc server URL/command. --config selects a read-only session file."
+              : hasConfig && hasHeaders
+                ? "--header cannot be combined with --config. Set per-server headers inside the config file instead."
+                : hasConfig && hasProtocolEra
+                  ? "--protocol-era cannot be combined with --config. Set protocolEra per server inside the config file instead."
+                  : null;
   if (conflict) {
     console.error(`Error: ${conflict}`);
     process.exit(1);
@@ -217,13 +233,18 @@ export async function runWeb(argv: string[]): Promise<number> {
 
     initialMcpConfig = config;
 
-    // In-memory session entry: the SDK config plus the flat `headers` record,
-    // which the backend lifts into `settings.headers` on read. Nothing is
-    // written to disk — the ad-hoc server is a read-only session list.
+    // In-memory session entry: the SDK config plus the flat `headers` record
+    // and `protocolEra`, which the backend lifts into `settings` on read.
+    // Nothing is written to disk — the ad-hoc server is a read-only session
+    // list. The era is transport-agnostic, so unlike `--header` it applies to
+    // stdio too.
     const entry: StoredMCPServer =
       hasHeaders && config.type !== "stdio" && config.type !== undefined
         ? { ...config, headers: opts.header }
         : { ...config };
+    if (opts.protocolEra !== undefined) {
+      entry.protocolEra = opts.protocolEra;
+    }
     initialServers = {
       mcpServers: { [deriveSeedServerId(config)]: entry },
     };
@@ -233,6 +254,11 @@ export async function runWeb(argv: string[]): Promise<number> {
       "Error: --header requires an ad-hoc --server-url or command target.",
     );
     process.exit(1);
+  } else if (hasProtocolEra) {
+    console.error(
+      "Error: --protocol-era requires an ad-hoc --server-url or command target.",
+    );
+    process.exit(1);
   }
 
   let webConfig: WebServerConfig;

clients/web/src/test/core/mcp/node/config.test.ts

@@ -12,6 +12,7 @@ import { join } from "node:path";
 import {
   parseKeyValuePair,
   parseHeaderPair,
+  parseProtocolEra,
   withDefaultCatalogPath,
   resolveServerConfigs,
   resolveServerSource,
@@ -44,6 +45,18 @@ describe("parseKeyValuePair", () => {
   });
 });
 
+describe("parseProtocolEra", () => {
+  it.each(["legacy", "auto", "modern"])("accepts %s", (era) => {
+    expect(parseProtocolEra(era)).toBe(era);
+  });
+
+  it("rejects an unknown era, naming the valid ones", () => {
+    expect(() => parseProtocolEra("Modern")).toThrow(
+      "Invalid protocol era: Modern. Valid eras are: legacy, auto, modern",
+    );
+  });
+});
+
 describe("parseHeaderPair", () => {
   it("splits on the first colon and trims both sides", () => {
     expect(parseHeaderPair("X-Test:   value")).toEqual({

clients/web/src/test/core/mcp/node/servers.test.ts

@@ -234,6 +234,74 @@ describe("loadServerEntries", () => {
     ).rejects.toThrow(/--catalog cannot be combined/);
   });
 
+  it("overrides the disk protocolEra with --protocol-era, preserving the rest", async () => {
+    const configPath = join(tempDir, "mcp.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        mcpServers: {
+          web: {
+            type: "streamable-http",
+            url: "http://x/mcp",
+            headers: { Authorization: "Bearer disk" },
+            protocolEra: "auto",
+            requestTimeout: 9000,
+          },
+        },
+      }),
+    );
+
+    const servers = await loadServerEntries({
+      configPath,
+      protocolEra: "modern",
+    });
+    expect(servers.web?.settings?.protocolEra).toBe("modern");
+    expect(servers.web?.settings?.requestTimeout).toBe(9000);
+    expect(servers.web?.settings?.headers).toEqual([
+      { key: "Authorization", value: "Bearer disk" },
+    ]);
+  });
+
+  it("applies --protocol-era to a server that has no disk settings", async () => {
+    const configPath = join(tempDir, "mcp.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        mcpServers: {
+          web: { type: "streamable-http", url: "http://x/mcp" },
+        },
+      }),
+    );
+
+    const servers = await loadServerEntries({
+      configPath,
+      protocolEra: "auto",
+    });
+    expect(servers.web?.settings).toMatchObject({
+      protocolEra: "auto",
+      headers: [],
+      connectionTimeout: DEFAULT_CONNECTION_TIMEOUT_MS,
+    });
+  });
+
+  it("applies --protocol-era and --header together to an ad-hoc URL", async () => {
+    const servers = await loadServerEntries({
+      serverUrl: "http://x/mcp",
+      transport: "http",
+      headers: { Authorization: "Bearer t" },
+      protocolEra: "modern",
+    });
+    expect(servers.default?.settings).toMatchObject({
+      protocolEra: "modern",
+      headers: [{ key: "Authorization", value: "Bearer t" }],
+    });
+  });
+
+  it("gives an ad-hoc target with neither flag no settings (legacy default)", async () => {
+    const servers = await loadServerEntries({ target: ["my-server"] });
+    expect(servers.default?.settings).toBeUndefined();
+  });
+
   it("builds a single ad-hoc server from a positional target", async () => {
     const servers = await loadServerEntries({
       target: ["my-server", "--flag"],

clients/web/src/test/integration/server/run-web.test.ts

@@ -327,6 +327,83 @@ describe("runWeb", () => {
     expect(startHonoServer).not.toHaveBeenCalled();
   });
 
+  it("plumbs --protocol-era onto the seeded ad-hoc HTTP server", async () => {
+    void runWeb([
+      "node",
+      "run-web",
+      "--server-url",
+      "https://example.com/mcp",
+      "--transport",
+      "http",
+      "--header",
+      "Authorization: Bearer x",
+      "--protocol-era",
+      "modern",
+    ]);
+    await expectServerStarted(startHonoServer);
+
+    expect(soleSeededEntry()).toMatchObject({
+      type: "streamable-http",
+      url: "https://example.com/mcp",
+      headers: { Authorization: "Bearer x" },
+      protocolEra: "modern",
+    });
+  });
+
+  it("plumbs --protocol-era onto a seeded ad-hoc stdio server", async () => {
+    void runWeb([
+      "node",
+      "run-web",
+      "--protocol-era",
+      "auto",
+      "node",
+      "server.js",
+    ]);
+    await expectServerStarted(startHonoServer);
+
+    expect(soleSeededEntry()).toMatchObject({
+      command: "node",
+      args: ["server.js"],
+      protocolEra: "auto",
+    });
+  });
+
+  it("omits protocolEra from the seeded entry when the flag is absent", async () => {
+    void runWeb([
+      "node",
+      "run-web",
+      "https://example.com/mcp",
+      "--transport",
+      "http",
+    ]);
+    await expectServerStarted(startHonoServer);
+
+    expect(soleSeededEntry()).not.toHaveProperty("protocolEra");
+  });
+
+  it("rejects an unknown --protocol-era value", async () => {
+    await expect(
+      runWeb([
+        "node",
+        "run-web",
+        "https://example.com/mcp",
+        "--protocol-era",
+        "future",
+      ]),
+    ).rejects.toThrow();
+    expect(startHonoServer).not.toHaveBeenCalled();
+  });
+
+  it("rejects --protocol-era with no ad-hoc server to attach it to", async () => {
+    await expect(
+      runWeb(["node", "run-web", "--protocol-era", "modern"]),
+    ).rejects.toThrow("process.exit:1");
+    expect(
+      errorLines.some((l) => l.includes("--protocol-era requires an ad-hoc")),
+    ).toBe(true);
+    expect(startHonoServer).not.toHaveBeenCalled();
+  });
+
   it("exits when an ad-hoc config resolves to no entries", async () => {
     vi.spyOn(nodeConfig, "resolveServerConfigs").mockReturnValueOnce([]);
 
@@ -548,6 +625,16 @@ describe("runWeb", () => {
       argv: ["--config", "/a.json", "--header", "Authorization: Bearer x"],
       match: "--header cannot be combined with --config",
     },
+    {
+      name: "--catalog + --protocol-era",
+      argv: ["--catalog", "/a.json", "--protocol-era", "modern"],
+      match: "--protocol-era cannot be combined with --catalog",
+    },
+    {
+      name: "--config + --protocol-era",
+      argv: ["--config", "/a.json", "--protocol-era", "modern"],
+      match: "--protocol-era cannot be combined with --config",
+    },
   ])("rejects $name", async ({ argv, match }) => {
     await expect(runWeb(["node", "run-web", ...argv])).rejects.toThrow(
       "process.exit:1",