@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/surfaces/harness-registry.d.ts

@@ -31,6 +31,22 @@ export declare const HARNESS_REGISTRY: readonly [Readonly<{
         measuredVersion: "2.1.317";
         provenance: "a SessionStart hook in .claude/settings.json ran under claude -p and the agent quoted its stdout back, while a hook under a misspelled event name never ran and Claude Code named it as ignored";
     }>;
+    remoteMcp: Readonly<{
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string;
+        helper: boolean;
+        provenance: string;
+        state: 'instructed';
+        headers: true;
+        measuredOn: "2026-11-04";
+    }>;
+    servedCheckoutGrant: Readonly<{
+        state: 'enforced' | 'unavailable';
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string | null;
+        provenance: string;
+        measuredOn: "2026-11-04";
+    }>;
 }>, Readonly<{
     target: "codexcli";
     type: 'agent';
@@ -64,6 +80,22 @@ export declare const HARNESS_REGISTRY: readonly [Readonly<{
         measuredVersion: "0.166.0";
         provenance: "only after a person trusts the hook, as for the guard: a trusted SessionStart hook in .codex/hooks.json ran under codex exec and the agent quoted its stdout back, while a hook under a misspelled event name never ran";
     }>;
+    remoteMcp: Readonly<{
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string;
+        helper: boolean;
+        provenance: string;
+        state: 'instructed';
+        headers: true;
+        measuredOn: "2026-11-04";
+    }>;
+    servedCheckoutGrant: Readonly<{
+        state: 'enforced' | 'unavailable';
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string | null;
+        provenance: string;
+        measuredOn: "2026-11-04";
+    }>;
 }>, Readonly<{
     target: "opencode";
     type: 'agent';
@@ -97,6 +129,22 @@ export declare const HARNESS_REGISTRY: readonly [Readonly<{
         measuredVersion: null;
         provenance: string;
     };
+    remoteMcp: Readonly<{
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string;
+        helper: boolean;
+        provenance: string;
+        state: 'instructed';
+        headers: true;
+        measuredOn: "2026-11-04";
+    }>;
+    servedCheckoutGrant: Readonly<{
+        state: 'enforced' | 'unavailable';
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string | null;
+        provenance: string;
+        measuredOn: "2026-11-04";
+    }>;
 }>, Readonly<{
     target: "cursor";
     type: 'agent';
@@ -126,6 +174,22 @@ export declare const HARNESS_REGISTRY: readonly [Readonly<{
         measuredVersion: null;
         provenance: string;
     };
+    remoteMcp: Readonly<{
+        state: 'unavailable';
+        evidence: 'not_applicable';
+        headers: false;
+        helper: false;
+        measuredOn: "2026-11-04";
+        measuredVersion: null;
+        provenance: "cockpit writes no remote MCP server for this tool: its remote transport and header spelling have not been checked";
+    }>;
+    servedCheckoutGrant: Readonly<{
+        state: 'enforced' | 'unavailable';
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string | null;
+        provenance: string;
+        measuredOn: "2026-11-04";
+    }>;
 }>, Readonly<{
     target: "grokcli";
     type: 'agent';
@@ -155,6 +219,22 @@ export declare const HARNESS_REGISTRY: readonly [Readonly<{
         measuredVersion: null;
         provenance: string;
     };
+    remoteMcp: Readonly<{
+        state: 'unavailable';
+        evidence: 'not_applicable';
+        headers: false;
+        helper: false;
+        measuredOn: "2026-11-04";
+        measuredVersion: null;
+        provenance: "cockpit writes no remote MCP server for this tool: its remote transport and header spelling have not been checked";
+    }>;
+    servedCheckoutGrant: Readonly<{
+        state: 'enforced' | 'unavailable';
+        evidence: 'not_applicable' | 'human_needed';
+        measuredVersion: string | null;
+        provenance: string;
+        measuredOn: "2026-11-04";
+    }>;
 }>];
 export type HarnessRegistryRow = typeof HARNESS_REGISTRY[number];
 export type SurfaceTarget = HarnessRegistryRow['target'];

package/dist/surfaces/harness-registry.js

@@ -44,6 +44,21 @@ const codexSessionStart = Object.freeze({
     provenance: 'only after a person trusts the hook, as for the guard: a trusted SessionStart hook in .codex/hooks.json ran under codex exec and the agent quoted its stdout back, while a hook under a misspelled event name never ran',
 });
 const noSessionStart = (reason) => ({ state: 'unavailable', evidence: 'not_applicable', measuredOn: '2026-11-03', measuredVersion: null, provenance: reason });
+// What each tool's native MCP file can say for a remote (streamable HTTP) server. A header must come
+// from an environment reference or a headers helper, never a literal; a tool that cannot express a
+// server's credential gets nothing for that server, because a server written without it would start,
+// fail to authenticate and read as configured. Each run connected the tool to a loopback server that
+// recorded the request headers, beside a control spelled the way the tool does not read.
+const remoteMcpMeasured = (fact) => Object.freeze({ state: 'instructed', headers: true, measuredOn: '2026-11-04', ...fact });
+const noRemoteMcp = Object.freeze({ state: 'unavailable', evidence: 'not_applicable', headers: false, helper: false,
+    measuredOn: '2026-11-04', measuredVersion: null,
+    provenance: 'cockpit writes no remote MCP server for this tool: its remote transport and header spelling have not been checked' });
+// Whether `cockpit use` can grant a checkout served from outside the declared one through a
+// machine-local file the tool reads. Each run wrote into the granted directory and into an
+// ungranted control beside it.
+const servedGrant = (fact) => Object.freeze({ measuredOn: '2026-11-04', ...fact });
+const noServedGrant = servedGrant({ state: 'unavailable', evidence: 'not_applicable', measuredVersion: null,
+    provenance: 'the tool was not installed where this was measured, so cockpit use writes nothing for it' });
 const completeRulesyncFeatures = Object.freeze(['rules', 'mcp', 'subagents', 'skills', 'hooks', 'permissions']);
 const nonPermissionRulesyncFeatures = Object.freeze(['rules', 'mcp', 'subagents', 'skills', 'hooks']);
 export const HARNESS_REGISTRY = Object.freeze([
@@ -52,12 +67,20 @@ export const HARNESS_REGISTRY = Object.freeze([
         rulesyncFeatures: completeRulesyncFeatures,
         outputs: Object.freeze({ instruction: 'CLAUDE.md', skills: '.claude/skills', mcp: '.mcp.json', permissions: Object.freeze(['.claude/settings.json']) }),
         guard: Object.freeze({ capability: 'instructed', firing: claudeFiring }), native: reviewedNative, sessionStart: claudeSessionStart,
+        remoteMcp: remoteMcpMeasured({ evidence: 'human_needed', measuredVersion: '2.1.318', helper: true,
+            provenance: 'from a project .mcp.json, Claude Code sent the Authorization header a ${NAME} reference named while a $NAME control went out literally; it ran a headersHelper given with --mcp-config, but refused to run one from the project file until a person trusts the workspace, and a misspelled headerHelper sent nothing' }),
+        servedCheckoutGrant: servedGrant({ state: 'enforced', evidence: 'human_needed', measuredVersion: '2.1.318',
+            provenance: 'a directory in .claude/settings.local.json permissions.additionalDirectories was written and the control refused, and a malformed twin granted nothing; measured in an untrusted workspace, so whether it combines with the committed list once a person trusts the workspace is unmeasured' }),
     }),
     Object.freeze({
         target: 'codexcli', type: 'agent', displayName: 'Codex', rulesyncTarget: 'codexcli',
         rulesyncFeatures: completeRulesyncFeatures,
         outputs: Object.freeze({ instruction: 'AGENTS.md', skills: '.agents/skills', mcp: '.codex/config.toml', permissions: Object.freeze(['.codex/config.toml']) }),
         guard: Object.freeze({ capability: 'instructed', firing: codexFiring }), native: reviewedNative, sessionStart: codexSessionStart,
+        remoteMcp: remoteMcpMeasured({ evidence: 'not_applicable', measuredVersion: '0.166.0', helper: true,
+            provenance: 'from a project .codex/config.toml in a directory Codex had not been told to trust, codex exec sent the bearer_token_env_var and env_http_headers values and the http_headers_helper output, named a misspelled http_header_helper as ignored, and sent a ${NAME} written in http_headers literally' }),
+        servedCheckoutGrant: servedGrant({ state: 'unavailable', evidence: 'not_applicable', measuredVersion: '0.166.0',
+            provenance: 'Codex reads no machine-local project file; --add-dir at start made the worktree writable and without it the write was refused, so cockpit use prints that flag and writes nothing' }),
     }),
     Object.freeze({
         target: 'opencode', type: 'agent', displayName: 'OpenCode', rulesyncTarget: 'opencodev1',
@@ -67,6 +90,10 @@ export const HARNESS_REGISTRY = Object.freeze([
         // OpenCode 1.19.5 delivered session.created to a project plugin beside a misspelled hook that
         // never ran, but its model call failed, so no plugin hook was shown to put text in the agent's context.
         sessionStart: noSessionStart('OpenCode 1.19.5 delivers session.created to a plugin, but no run has shown a plugin putting text in the agent\'s context, so cockpit generates no session-start check'),
+        remoteMcp: remoteMcpMeasured({ evidence: 'not_applicable', measuredVersion: '1.19.5', helper: false,
+            provenance: 'opencode mcp list sent headers expanded from {env:NAME} in a project opencode.jsonc while a ${NAME} control went out literally; its remote server schema has no headers helper, so a server that declares one is not written for it' }),
+        servedCheckoutGrant: servedGrant({ state: 'enforced', evidence: 'not_applicable', measuredVersion: '1.19.5',
+            provenance: 'the machine-local grant file holding the worktree path allowed the write and the control was denied, and a pattern naming a missing grant file stopped OpenCode at start, naming the file' }),
     }),
     Object.freeze({
         target: 'cursor', type: 'agent', displayName: 'Cursor', rulesyncTarget: 'cursor',
@@ -74,12 +101,14 @@ export const HARNESS_REGISTRY = Object.freeze([
         // Rules overlays only: cockpit's own instructions reach Cursor through the root AGENTS.md.
         outputs: Object.freeze({ instruction: '.cursor/rules', skills: '.cursor/skills', mcp: '.cursor/mcp.json', permissions: Object.freeze(['.cursor/cli.json']) }),
         guard: noGuardAdapter, native: generatedNative, sessionStart: noSessionStart('cockpit generates no hook for this tool'),
+        remoteMcp: noRemoteMcp, servedCheckoutGrant: noServedGrant,
     }),
     Object.freeze({
         target: 'grokcli', type: 'agent', displayName: 'Grok Build', rulesyncTarget: 'grokcli',
         rulesyncFeatures: completeRulesyncFeatures,
         outputs: Object.freeze({ instruction: 'AGENTS.md', skills: '.grok/skills', mcp: '.grok/config.toml', permissions: Object.freeze(['.grok/config.toml']) }),
         guard: noGuardAdapter, native: generatedNative, sessionStart: noSessionStart('cockpit generates no hook for this tool'),
+        remoteMcp: noRemoteMcp, servedCheckoutGrant: noServedGrant,
     }),
 ]);
 export const SURFACE_TARGETS = Object.freeze(HARNESS_REGISTRY.map(row => row.target));

package/dist/surfaces/mcp.d.ts

@@ -14,7 +14,7 @@ declare const Source: z.ZodDiscriminatedUnion<[z.ZodObject<{
     sha256: z.ZodString;
     slug: z.ZodString;
 }, z.core.$strict>], "kind">;
-declare const Declaration: z.ZodObject<{
+declare const StdioDeclaration: z.ZodObject<{
     name: z.ZodString;
     command: z.ZodString;
     args: z.ZodArray<z.ZodString>;
@@ -35,25 +35,80 @@ declare const Declaration: z.ZodObject<{
         slug: z.ZodString;
     }, z.core.$strict>], "kind">;
 }, z.core.$strict>;
-export type McpSource = z.infer<typeof Source>;
-export type McpDeclaration = z.infer<typeof Declaration>;
+declare const HttpDeclaration: z.ZodObject<{
+    name: z.ZodString;
+    transport: z.ZodLiteral<"http">;
+    url: z.ZodString;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    helper: z.ZodNullable<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodArray<z.ZodString>;
+        cwd: z.ZodString;
+    }, z.core.$strict>>;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"core">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"overlay">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"sibling">;
+        path: z.ZodString;
+        sha256: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+type McpSource = z.infer<typeof Source>;
+export type McpStdioDeclaration = z.infer<typeof StdioDeclaration>;
+export type McpHttpDeclaration = z.infer<typeof HttpDeclaration>;
+type McpDeclaration = McpStdioDeclaration | McpHttpDeclaration;
 export interface McpDiagnostic {
-    readonly code: 'MCP_INPUT_INVALID' | 'MCP_DECLARATION_INVALID' | 'MCP_COMMAND_CONFLICT' | 'MCP_NOT_APPROVED' | 'MCP_APPROVAL_UNKNOWN';
+    readonly code: 'MCP_INPUT_INVALID' | 'MCP_DECLARATION_INVALID' | 'MCP_COMMAND_CONFLICT' | 'MCP_NOT_APPROVED' | 'MCP_APPROVAL_UNKNOWN' | 'MCP_TRANSPORT_UNAVAILABLE';
     readonly message: string;
     readonly server?: string;
     readonly sources?: readonly McpSource[];
     /** The approval digest of the server's current declaration, on MCP_NOT_APPROVED. */
     readonly sha256?: string;
+    /** The tools a server is not written for, on MCP_TRANSPORT_UNAVAILABLE. */
+    readonly targets?: readonly SurfaceTarget[];
 }
-interface McpServer {
-    readonly name: string;
+interface McpLaunch {
     readonly command: string;
     readonly args: readonly string[];
     readonly cwd: string;
-    readonly envNames: readonly string[];
-    readonly enabled: boolean;
-    readonly sources: readonly McpSource[];
 }
+export type McpServer = Readonly<{
+    name: string;
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    envNames: readonly string[];
+    enabled: boolean;
+    sources: readonly McpSource[];
+}> | Readonly<{
+    name: string;
+    transport: 'http';
+    url: string;
+    headers: Readonly<Record<string, string>>;
+    helper: McpLaunch | null;
+    envNames: readonly string[];
+    enabled: boolean;
+    sources: readonly McpSource[];
+}>;
+export type McpHarnessServer = Readonly<{
+    name: string;
+    command: string;
+    args: readonly string[];
+    enabled: boolean;
+}> | Readonly<{
+    name: string;
+    url: string;
+    headers: Readonly<Record<string, string>>;
+    headersHelper: string | null;
+    enabled: boolean;
+}>;
 export interface McpCollection {
     readonly servers: readonly McpServer[];
     readonly wrappers: readonly {
@@ -63,12 +118,7 @@ export interface McpCollection {
     }[];
     readonly harnesses: readonly {
         readonly target: SurfaceTarget;
-        readonly servers: readonly {
-            readonly name: string;
-            readonly command: string;
-            readonly args: readonly string[];
-            readonly enabled: boolean;
-        }[];
+        readonly servers: readonly McpHarnessServer[];
     }[];
 }
 export type McpCollectionOutcome = Readonly<{
@@ -79,14 +129,14 @@ export type McpCollectionOutcome = Readonly<{
     kind: 'refusal';
     diagnostic: McpDiagnostic;
 }>;
-export type McpParseOutcome = Readonly<{
+type McpParseOutcome = Readonly<{
     kind: 'complete';
     declarations: readonly McpDeclaration[];
 }> | Readonly<{
     kind: 'refusal';
     diagnostic: McpDiagnostic;
 }>;
-type McpIdentity = Pick<McpDeclaration, 'command' | 'args' | 'cwd' | 'envNames'>;
+type McpIdentity = Pick<McpStdioDeclaration, 'command' | 'args' | 'cwd' | 'envNames'> | Pick<McpHttpDeclaration, 'transport' | 'url' | 'headers' | 'helper'>;
 /** The digest `[mcp.approved]` records for a server, so a changed declaration is no longer approved. */
 export declare function mcpApprovalDigest(declaration: McpIdentity, cockpitDirectory: string): string;
 export declare function collectMcpDeclarations(input: unknown): McpCollectionOutcome;

package/dist/surfaces/mcp.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { sha256Hex } from '../sha256.js';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { z } from 'zod';
 import { parseDocument } from 'yaml';
@@ -20,14 +20,69 @@ const Source = z.discriminatedUnion('kind', [
 ]);
 const Argument = ShellToken.refine(value => !/^--?(?:api[-_]?key|token|password|secret|authorization|credential)(?:=|$)/i.test(value)
     && !/^[a-z][a-z0-9+.-]*:\/\/[^/]*@/i.test(value));
-const Declaration = z.object({
+const Command = ShellToken.refine(value => !value.startsWith('-'));
+const StdioDeclaration = z.object({
     name: ServerName,
-    command: ShellToken.refine(value => !value.startsWith('-')),
+    command: Command,
     args: z.array(Argument).max(256),
     cwd: WorkingDirectory,
     envNames: z.array(EnvironmentName).max(128).refine(names => new Set(names).size === names.length),
     source: Source,
 }).strict();
+const LOOPBACK_HOSTS = /^(?:localhost|127(?:\.\d{1,3}){3}|\[::1\])$/;
+const CREDENTIAL_NAME = /^(?:api[-_]?key|token|access[-_]?token|password|secret|authorization|credential)$/i;
+/** Why a remote MCP URL is refused, or undefined when it is accepted. Never echoes the URL. */
+function remoteMcpUrlProblem(value) {
+    // OpenCode expands {env:NAME} and {file:path} anywhere in opencode.jsonc, URL included, so a brace
+    // would let a declaration send an environment variable or a file's contents to the server.
+    if (/[{}]/.test(value))
+        return 'contains a brace, which OpenCode expands as {env:...} or {file:...} and Codex sends literally';
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return 'is not an absolute URL';
+    }
+    if (url.username || url.password)
+        return 'carries credentials in its user information';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK_HOSTS.test(url.hostname))) {
+        return 'must use https, or http only to a loopback host';
+    }
+    if ([...url.searchParams.keys()].some(name => CREDENTIAL_NAME.test(name)))
+        return 'carries a credential-named query parameter';
+    return undefined;
+}
+// A header value is one environment reference, whole or after `Bearer ` in Authorization. Those are
+// the only spellings all three tools resolve from the environment (Codex reads them as
+// env_http_headers and bearer_token_env_var), so no credential literal reaches a tracked file.
+const HEADER_REFERENCE = /^(Bearer )?\$\{([A-Z][A-Z0-9_]*)\}$/;
+const HeaderName = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9-]*$/).max(128);
+/** Why a declared header is refused, or undefined when it is an accepted environment reference. Never echoes the value. */
+function remoteMcpHeaderProblem(name, value) {
+    if (!HeaderName.safeParse(name).success)
+        return 'has a name that is not an HTTP token';
+    const match = HEADER_REFERENCE.exec(value);
+    if (!match)
+        return 'must be exactly ${NAME}, or Bearer ${NAME} for Authorization, naming an upper-case environment variable; a literal value would commit the credential';
+    if (match[1] && name.toLowerCase() !== 'authorization')
+        return 'may use the Bearer form only in Authorization';
+    return undefined;
+}
+const Headers = z.record(z.string(), z.string().max(256))
+    .refine(headers => Object.keys(headers).length <= 32
+    && Object.entries(headers).every(([name, value]) => remoteMcpHeaderProblem(name, value) === undefined)
+    && new Set(Object.keys(headers).map(name => name.toLowerCase())).size === Object.keys(headers).length);
+const HttpDeclaration = z.object({
+    name: ServerName,
+    transport: z.literal('http'),
+    url: z.string().max(2048).refine(url => remoteMcpUrlProblem(url) === undefined),
+    headers: Headers,
+    // The declared command that prints the request headers as a JSON object when the tool connects.
+    helper: z.object({ command: Command, args: z.array(Argument).max(64), cwd: WorkingDirectory }).strict().nullable(),
+    source: Source,
+}).strict();
+const Declaration = z.union([StdioDeclaration, HttpDeclaration]);
 const Input = z.object({
     cockpitDirectory: WorkingDirectory,
     declarations: z.array(Declaration).max(256),
@@ -45,29 +100,49 @@ function quote(value) {
 // server's directory is relative to it: the committed bytes are the same in every clone. The `./`
 // keeps CDPATH from choosing another directory and printing it into the JSON-RPC stream, and `-P`
 // resolves `..` from the real root, against which the relative path was computed.
-function wrapper(server, cockpitDirectory) {
-    const inherited = ['PATH', ...INHERITED_TOOL_ENVIRONMENT].filter(name => !server.envNames.includes(name));
+// A headers helper runs through the same kind of wrapper: Claude Code and Codex start it with
+// `sh -c` from the directory the agent was launched in, and it prints the headers on stdout.
+function wrapper(launch, envNames, cockpitDirectory) {
+    const inherited = ['PATH', ...INHERITED_TOOL_ENVIRONMENT].filter(name => !envNames.includes(name));
     return [
         '#!/bin/sh',
         'set -eu',
-        `cd -P -- ${quote(`./${relative(cockpitDirectory, server.cwd) || '.'}`)}`,
-        `executable=$(command -v ${quote(server.command)}) || { printf '%s\\n' 'MCP_EXECUTABLE_UNAVAILABLE' >&2; exit 2; }`,
+        `cd -P -- ${quote(`./${relative(cockpitDirectory, launch.cwd) || '.'}`)}`,
+        `executable=$(command -v ${quote(launch.command)}) || { printf '%s\\n' 'MCP_EXECUTABLE_UNAVAILABLE' >&2; exit 2; }`,
         '[ -f "$executable" ] && [ -x "$executable" ] || { printf \'%s\\n\' \'MCP_EXECUTABLE_UNAVAILABLE\' >&2; exit 2; }',
         // `npx`, `uvx` and most npm servers are `#!/usr/bin/env node` scripts: without PATH they
         // cannot start. The rest of the inherited set carries caches and locale, never a credential.
         `exec /usr/bin/env -i ${inherited.map(name => `\${${name}+"${name}=$${name}"}`).join(' ')}`
-            + `${server.envNames.map(name => ` ${name}="\${${name}?required environment name ${name} is unset}"`).join('')} "$executable"${server.args.map(arg => ` ${quote(arg)}`).join('')}`,
+            + `${envNames.map(name => ` ${name}="\${${name}?required environment name ${name} is unset}"`).join('')} "$executable"${launch.args.map(arg => ` ${quote(arg)}`).join('')}`,
         '',
     ].join('\n');
 }
-// What a human reviews before approving a server: everything the wrapper runs. The working
-// directory is taken relative to the cockpit so the digest is the same in every clone.
+/** The committed path of a server's stdio wrapper, or of its headers helper wrapper. */
+function mcpWrapperPath(name, kind) {
+    return `.cockpit/mcp/${sha256Hex(name)}${kind === 'headers' ? '.headers' : ''}.sh`;
+}
+function isHttp(value) {
+    return 'transport' in value && value.transport === 'http';
+}
+function headerEnvironmentNames(headers) {
+    return [...new Set(Object.values(headers).map(value => HEADER_REFERENCE.exec(value)[2]))].sort();
+}
+// What a human reviews before approving a server: everything the wrapper runs, or the URL, the
+// header references and the helper a remote server connects with. Working directories are taken
+// relative to the cockpit so the digest is the same in every clone.
 function identity(declaration, cockpitDirectory) {
-    return JSON.stringify({ command: declaration.command, args: declaration.args, cwd: relative(cockpitDirectory, declaration.cwd) || '.', envNames: [...declaration.envNames].sort() });
+    if (isHttp(declaration)) {
+        const helper = declaration.helper;
+        return JSON.stringify({ transport: 'http', url: declaration.url,
+            headers: Object.entries(declaration.headers).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0),
+            helper: helper && { command: helper.command, args: helper.args, cwd: relative(cockpitDirectory, helper.cwd) || '.' } });
+    }
+    const stdio = declaration;
+    return JSON.stringify({ command: stdio.command, args: stdio.args, cwd: relative(cockpitDirectory, stdio.cwd) || '.', envNames: [...stdio.envNames].sort() });
 }
 /** The digest `[mcp.approved]` records for a server, so a changed declaration is no longer approved. */
 export function mcpApprovalDigest(declaration, cockpitDirectory) {
-    return createHash('sha256').update(identity(declaration, cockpitDirectory)).digest('hex');
+    return sha256Hex(identity(declaration, cockpitDirectory));
 }
 export function collectMcpDeclarations(input) {
     const captured = snapshotJson(input);
@@ -81,7 +156,7 @@ export function collectMcpDeclarations(input) {
         if (prior && identity(prior.declaration, cockpitDirectory) !== identity(declaration, cockpitDirectory)) {
             const conflict = snapshotJson({ kind: 'refusal', diagnostic: {
                     code: 'MCP_COMMAND_CONFLICT', server: declaration.name,
-                    message: 'MCP server identity has divergent command, arguments, working directory or environment names',
+                    message: 'MCP server identity has divergent declarations: command, arguments, working directory or environment names for a local server; URL, header references or headers helper for a remote one',
                     sources: [...prior.sources, declaration.source],
                 } });
             return conflict ? conflict
@@ -95,11 +170,17 @@ export function collectMcpDeclarations(input) {
             collected.set(declaration.name, { declaration, sources: [declaration.source] });
     }
     const digests = new Map([...collected].map(([name, { declaration }]) => [name, mcpApprovalDigest(declaration, cockpitDirectory)]));
-    const servers = [...collected.values()].map(({ declaration, sources }) => ({
-        name: declaration.name, command: declaration.command, args: declaration.args, cwd: declaration.cwd,
-        envNames: [...declaration.envNames].sort(), enabled: Object.hasOwn(approved, declaration.name) && approved[declaration.name] === digests.get(declaration.name),
-        sources: sources.sort((left, right) => JSON.stringify(left) < JSON.stringify(right) ? -1 : JSON.stringify(left) > JSON.stringify(right) ? 1 : 0),
-    })).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    const servers = [...collected.values()].map(({ declaration, sources }) => {
+        const shared = {
+            enabled: Object.hasOwn(approved, declaration.name) && approved[declaration.name] === digests.get(declaration.name),
+            sources: sources.sort((left, right) => JSON.stringify(left) < JSON.stringify(right) ? -1 : JSON.stringify(left) > JSON.stringify(right) ? 1 : 0),
+        };
+        return isHttp(declaration)
+            ? { name: declaration.name, transport: 'http', url: declaration.url, headers: declaration.headers, helper: declaration.helper,
+                envNames: headerEnvironmentNames(declaration.headers), ...shared }
+            : { name: declaration.name, command: declaration.command, args: declaration.args, cwd: declaration.cwd,
+                envNames: [...declaration.envNames].sort(), ...shared };
+    }).sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
     const diagnostics = servers.filter(server => !server.enabled).map(server => ({
         code: 'MCP_NOT_APPROVED', server: server.name, sources: server.sources, sha256: digests.get(server.name),
         message: 'MCP server has no shared approval for its current declaration and remains disabled',
@@ -109,26 +190,61 @@ export function collectMcpDeclarations(input) {
             diagnostics.push({
                 code: 'MCP_APPROVAL_UNKNOWN', server: name, message: 'The shared approval list names an undeclared MCP server',
             });
-    const wrappers = servers.map(server => {
-        const bytes = wrapper(server, cockpitDirectory);
-        return { path: `.cockpit/mcp/${createHash('sha256').update(server.name).digest('hex')}.sh`, bytes, sha256: createHash('sha256').update(bytes).digest('hex') };
-    });
+    // A tool that cannot carry a remote server's credential gets nothing for it: written without
+    // its headers, the server would start, fail to authenticate and still read as configured.
+    const writes = (server, target) => {
+        if (!isHttp(server))
+            return true;
+        const support = harnessFact(target).remoteMcp;
+        return support.state !== 'unavailable' && (Object.keys(server.headers).length === 0 || support.headers)
+            && (server.helper === null || support.helper);
+    };
+    const targets = parsed.data.targets;
+    for (const server of servers) {
+        const skipped = targets.filter(target => !writes(server, target));
+        if (skipped.length > 0)
+            diagnostics.push({
+                code: 'MCP_TRANSPORT_UNAVAILABLE', server: server.name, sources: server.sources, targets: skipped,
+                message: `MCP server is not written for ${skipped.join(', ')}: ${skipped.map(target => harnessFact(target).remoteMcp.provenance).filter((reason, index, all) => all.indexOf(reason) === index).join('; ')}`,
+            });
+    }
+    const wrappers = [];
+    const launchers = new Map();
+    for (const server of servers) {
+        const launch = isHttp(server) ? server.helper : server;
+        if (launch === null || !targets.some(target => writes(server, target)))
+            continue;
+        const path = mcpWrapperPath(server.name, isHttp(server) ? 'headers' : 'server');
+        const bytes = wrapper(launch, isHttp(server) ? [] : server.envNames, cockpitDirectory);
+        wrappers.push({ path, bytes, sha256: sha256Hex(bytes) });
+        launchers.set(server.name, path);
+    }
     const result = {
         servers, wrappers,
-        harnesses: parsed.data.targets.map(target => ({ target, servers: servers.map((server, index) => ({
-                name: server.name, command: '/bin/sh', args: [wrappers[index].path], enabled: server.enabled,
-            })) })),
+        harnesses: targets.map(target => ({ target, servers: servers.filter(server => writes(server, target)).map((server) => isHttp(server)
+                ? { name: server.name, url: server.url, headers: server.headers,
+                    headersHelper: launchers.has(server.name) ? `/bin/sh ${launchers.get(server.name)}` : null, enabled: server.enabled }
+                : { name: server.name, command: '/bin/sh', args: [launchers.get(server.name)], enabled: server.enabled }) })),
     };
     const outcome = snapshotJson({ kind: 'complete', result, diagnostics });
     return outcome ? outcome : refuse('MCP_INPUT_INVALID', 'Canonical MCP output exceeds the bounded data budget');
 }
 const NativeServer = z.object({
-    type: z.literal('stdio').optional(), command: Declaration.shape.command,
+    type: z.literal('stdio').optional(), command: Command,
     args: z.array(Argument).max(256).default([]), cwd: RelativePath.or(z.literal('.')).optional(),
     env: z.record(EnvironmentName, z.string().max(128)).default({}),
 }).strict();
+// Claude Code's `.mcp.json` spelling of a remote server; values are checked one by one below so a
+// refusal can say which part is wrong without repeating it.
+const NativeHttpServer = z.object({
+    type: z.literal('http'), url: z.string().max(2048),
+    headers: z.record(z.string(), z.string().max(256)).default({}), headersHelper: z.string().min(1).max(4096).optional(),
+}).strict();
 // Absence is inferred only from cockpit's neutral shape; other source forms retain generator validation.
-const GeneratedServer = NativeServer.extend({ cwd: WorkingDirectory.optional(), disabled: z.boolean().optional() });
+const GeneratedServer = z.union([
+    NativeServer.extend({ cwd: WorkingDirectory.optional(), disabled: z.boolean().optional() }),
+    NativeHttpServer.extend({ http_headers_helper: z.string().min(1).max(4096).optional(), disabled: z.boolean().optional() }),
+]);
 const GeneratedServers = z.record(ServerName, GeneratedServer);
 const TargetServers = z.object({ mcpServers: z.record(ServerName, GeneratedServer.nullable()).optional() }).strict();
 export function hasTargetMcpServers(sources, target) {
@@ -155,23 +271,70 @@ export function hasTargetMcpServers(sources, target) {
         return true;
     }
 }
-const NativeFile = z.object({ mcpServers: z.record(ServerName, NativeServer).refine(servers => Object.keys(servers).length <= 256) }).strict();
+const NativeFile = z.object({ mcpServers: z.record(ServerName, z.unknown()).refine(servers => Object.keys(servers).length <= 256) }).strict();
 const ParseInput = z.object({ bytes: z.string(), source: Source, workingDirectory: WorkingDirectory }).strict();
+// A helper is written as one command line in `.mcp.json`. Cockpit runs it without a shell, so each
+// space-separated word must be plain: quoting, expansion and redirection belong in the helper script.
+const HELPER_WORD = /^[A-Za-z0-9_@%+=:,.\/-]+$/;
+function parseHttpServer(name, server, source, workingDirectory) {
+    const urlProblem = remoteMcpUrlProblem(server.url);
+    if (urlProblem)
+        return `MCP server ${name}: its url ${urlProblem}`;
+    const headerNames = Object.keys(server.headers);
+    if (headerNames.length > 32)
+        return `MCP server ${name} declares more than 32 headers`;
+    if (new Set(headerNames.map(header => header.toLowerCase())).size !== headerNames.length)
+        return `MCP server ${name} declares a header twice in different case`;
+    for (const [header, value] of Object.entries(server.headers)) {
+        const problem = remoteMcpHeaderProblem(header, value);
+        if (problem)
+            return `MCP server ${name}: header ${HeaderName.safeParse(header).success ? header : '(unnamed)'} ${problem}`;
+    }
+    let helper = null;
+    if (server.headersHelper !== undefined) {
+        const words = server.headersHelper.split(' ');
+        if (words.some(word => !HELPER_WORD.test(word)) || words[0].startsWith('-')) {
+            return `MCP server ${name}: headersHelper must be a command and arguments separated by single spaces, without quotes, variables or shell operators`;
+        }
+        helper = { command: words[0], args: words.slice(1), cwd: workingDirectory };
+        if (!z.array(Argument).safeParse(helper.args).success)
+            return `MCP server ${name}: headersHelper arguments must not carry a credential`;
+    }
+    return { name, transport: 'http', url: server.url, headers: server.headers, helper, source };
+}
 export function parseMcpDeclarationFile(input) {
     const parsed = ParseInput.safeParse(snapshotJson(input));
     if (!parsed.success)
         return refuse('MCP_DECLARATION_INVALID', 'MCP source must be bounded authenticated declaration bytes');
     const { bytes, source, workingDirectory } = parsed.data;
-    if (createHash('sha256').update(bytes).digest('hex') !== source.sha256)
+    if (sha256Hex(bytes) !== source.sha256)
         return refuse('MCP_DECLARATION_INVALID', 'MCP source digest does not match declaration bytes');
     const value = tryParseJson(bytes);
     if (value === undefined)
         return refuse('MCP_DECLARATION_INVALID', 'MCP declaration is not valid JSON');
     const file = NativeFile.safeParse(value);
     if (!file.success)
-        return refuse('MCP_DECLARATION_INVALID', 'MCP declaration contains unsupported command, environment or transport fields');
+        return refuse('MCP_DECLARATION_INVALID', 'MCP declaration must be one mcpServers object of at most 256 named servers');
     const declarations = [];
-    for (const [name, server] of Object.entries(file.data.mcpServers)) {
+    for (const [name, entry] of Object.entries(file.data.mcpServers)) {
+        const type = typeof entry === 'object' && entry !== null && 'type' in entry ? entry.type : undefined;
+        if (type === 'sse') {
+            return refuse('MCP_DECLARATION_INVALID', `MCP server ${name} uses the SSE transport, which Codex cannot connect to; declare the server's streamable HTTP endpoint with type http`);
+        }
+        if (type === 'http') {
+            const remote = NativeHttpServer.safeParse(entry);
+            if (!remote.success)
+                return refuse('MCP_DECLARATION_INVALID', `MCP server ${name} is a remote server with fields other than type, url, headers and headersHelper`);
+            const declaration = parseHttpServer(name, remote.data, source, workingDirectory);
+            if (typeof declaration === 'string')
+                return refuse('MCP_DECLARATION_INVALID', declaration);
+            declarations.push(declaration);
+            continue;
+        }
+        const local = NativeServer.safeParse(entry);
+        if (!local.success)
+            return refuse('MCP_DECLARATION_INVALID', 'MCP declaration contains unsupported command, environment or transport fields');
+        const server = local.data;
         if (Object.entries(server.env).some(([key, reference]) => reference !== `\${${key}}`)) {
             return refuse('MCP_DECLARATION_INVALID', 'MCP environment entries must reference their same declared environment name');
         }