@zgeoff/atc 2.37.0 → 2.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zgeoff/atc",
-  "version": "2.37.0",
+  "version": "2.39.0",
   "description": "Terminal control tower for coding-agent sessions",
   "homepage": "https://github.com/zgeoff/atc#readme",
   "bugs": "https://github.com/zgeoff/atc/issues",

package/src/agents/agent-adapter.ts

@@ -86,6 +86,22 @@ export interface GuestSpawnPlan extends SpawnPlan {
   readonly env?: Readonly<Record<string, string>>;
 }
 
+/**
+ * The project settings files the agent applies on top of what atc passes
+ * it, and the refusal for a file whose content would override or route
+ * around a sign-in through impd's broker, or null when it holds nothing
+ * that would. `files` are relative to the directory a harness starts in;
+ * `rootFiles` are relative to that directory, each directory above it, and
+ * the main checkout of the git worktree it lies in, since the agent reads
+ * them at a repository's root. `findRefusal` takes the file's absolute path
+ * on the host.
+ */
+export interface ProjectSettingsCheck {
+  readonly files: readonly string[];
+  readonly rootFiles: readonly string[];
+  readonly findRefusal: (path: string, content: string) => DaemonError | null;
+}
+
 export interface TranscriptToolUse {
   readonly name: string;
   readonly input: string;
@@ -269,6 +285,11 @@ export interface AgentAdapter {
   // The command that exits 0 inside a remote host when the agent there can
   // sign in without a person. Absent: atc runs no check.
   readonly planAuthCheck?: () => readonly string[];
+
+  // The project settings a remote launch behind impd's broker reads in
+  // the directory the harness starts in, before it starts. Absent: atc
+  // reads none.
+  readonly planProjectSettingsCheck?: () => ProjectSettingsCheck;
   readonly normalizeHook: (e: HookEvent) => AdapterEvent;
   readonly loadName: (
     source: string,

package/src/agents/build-claude-config-seed.ts

@@ -4,10 +4,12 @@ import { CLAUDE_CONFIG_SEED_FILE } from './claude-config-seed-file';
  * The guest file that seeds a session's own Claude config folder with the
  * state the CLI reads from `.claude.json` to start without its first-run
  * onboarding, and with folder trust for `trustedRoot`, the exact root of a
- * verified clone, when one is given. It holds no account: the placeholder
+ * verified clone, when one is given. Trust also approves every MCP server
+ * the clone's own `.mcp.json` declares, so an unattended session never
+ * waits on the CLI's approval prompt. It holds no account: the placeholder
  * credential is what keeps the CLI from asking for a login. Without a
- * trusted root the CLI asks a person to trust the workspace on its first
- * start.
+ * trusted root the CLI asks a person to trust the workspace, and to approve
+ * the clone's MCP servers, on its first start.
  */
 export function buildClaudeConfigSeed(
   trustedRoot: string | null,
@@ -15,9 +17,10 @@ export function buildClaudeConfigSeed(
   const seed =
     trustedRoot === null
       ? ONBOARDED_CONFIG
-      : { ...ONBOARDED_CONFIG, projects: { [trustedRoot]: { hasTrustDialogAccepted: true } } };
+      : { ...ONBOARDED_CONFIG, projects: { [trustedRoot]: TRUSTED_PROJECT } };
 
   return { [CLAUDE_CONFIG_SEED_FILE]: JSON.stringify(seed, null, 2) };
 }
 
 const ONBOARDED_CONFIG = { hasCompletedOnboarding: true };
+const TRUSTED_PROJECT = { hasTrustDialogAccepted: true, enableAllProjectMcpServers: true };

package/src/agents/build-claude-mcp-config.ts

@@ -0,0 +1,27 @@
+import type { ClaudeMCPServer } from '../shared/collect-claude-auth';
+
+/**
+ * The MCP config file that gives a session each server over HTTP with the
+ * broker's placeholder as a bearer credential in the server's header, so
+ * impd's broker swaps in the credential it holds for the server's host and
+ * the session never holds it.
+ */
+export function buildClaudeMCPConfig(servers: readonly ClaudeMCPServer[]): {
+  readonly mcpServers: Readonly<Record<string, unknown>>;
+} {
+  return {
+    mcpServers: Object.fromEntries(
+      servers.map((server) => [
+        server.name,
+        {
+          type: 'http',
+          url: server.url,
+          headers: { [server.header]: `Bearer ${BROKER_PLACEHOLDER}` },
+        },
+      ]),
+    ),
+  };
+}
+
+// The value impd's broker replaces with the credential on the host's side.
+const BROKER_PLACEHOLDER = 'imp-broker-placeholder';

package/src/agents/build-claude-project-settings-check.ts

@@ -0,0 +1,74 @@
+import { DaemonError } from '../protocol/daemon-error';
+import { isSubscriptionOverrideVariable } from '../shared/is-subscription-override-variable';
+import { isRecord } from '../shared/report';
+import type { ProjectSettingsCheck } from './agent-adapter';
+
+/**
+ * The check of a Claude CLI session's project settings before a launch
+ * behind impd's broker. The CLI applies a repository's
+ * `.claude/settings.json` from the directory it starts in, and its
+ * `.claude/settings.local.json` from there and from the repository's root
+ * or a worktree's main checkout, once the folder is trusted; a person can
+ * accept that trust inside the session. Each file refuses the launch when
+ * its `env` block sets a variable that would override the sign-in or route
+ * around the broker, or when it sets `apiKeyHelper`. A file that is not a
+ * JSON object refuses it too, since what the CLI would take from it is
+ * unknown. A refusal holds the setting's name, never its value.
+ */
+export function buildClaudeProjectSettingsCheck(agent: string): ProjectSettingsCheck {
+  return {
+    files: ['.claude/settings.json', LOCAL_SETTINGS_FILE],
+    rootFiles: [LOCAL_SETTINGS_FILE],
+    findRefusal: (file, content) => {
+      const setting = findOverrideSetting(content);
+
+      if (setting === null) {
+        return null;
+      }
+
+      const message =
+        setting === UNPARSEABLE
+          ? `agent '${agent}' signs in through impd's broker, but ${file} is not a JSON object, so atc cannot check it for settings that would override that sign-in`
+          : `agent '${agent}' signs in through impd's broker, but ${file} sets ${setting}, which would override or route around that sign-in`;
+
+      return new DaemonError('auth_target_unsupported', message, {
+        agent,
+        problem: 'project_settings_conflict',
+        file,
+        setting,
+      });
+    },
+  };
+}
+
+const LOCAL_SETTINGS_FILE = '.claude/settings.local.json';
+const UNPARSEABLE = '(unparseable)';
+
+// The first setting a project settings file holds that would override the
+// sign-in, as `env.<variable>` or `apiKeyHelper`, the unparseable marker
+// for content that is not a JSON object, or null when it holds none.
+function findOverrideSetting(content: string): string | null {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return UNPARSEABLE;
+  }
+
+  if (!isRecord(parsed) || Array.isArray(parsed)) {
+    return UNPARSEABLE;
+  }
+
+  if (parsed['apiKeyHelper'] !== undefined) {
+    return 'apiKeyHelper';
+  }
+
+  const env = parsed['env'];
+
+  const variable = isRecord(env)
+    ? Object.keys(env).find((key) => isSubscriptionOverrideVariable(key))
+    : undefined;
+
+  return variable === undefined ? null : `env.${variable}`;
+}

package/src/agents/claude-adapter.ts

@@ -23,6 +23,7 @@ import type {
   GuestSpawnPlan,
   HeadlessRunner,
   NameUpdate,
+  ProjectSettingsCheck,
   ResumeCheck,
   SpawnOptionSpecs,
   SpawnOptions,
@@ -32,7 +33,9 @@ import { buildArgsWithoutFlags } from './build-args-without-flags';
 import { buildATCBridgeFiles } from './build-atc-bridge-files';
 import { buildClaudeConfigSeed } from './build-claude-config-seed';
 import { buildClaudeGuestLaunch } from './build-claude-guest-launch';
+import { buildClaudeMCPConfig } from './build-claude-mcp-config';
 import { buildClaudeOverrideArgs } from './build-claude-override-args';
+import { buildClaudeProjectSettingsCheck } from './build-claude-project-settings-check';
 import { buildHookSettings } from './build-hook-settings';
 import type { HookSettingsProfile } from './build-hook-settings';
 import { buildRestoreModeArgs } from './build-restore-mode-args';
@@ -225,6 +228,12 @@ export class ClaudeAdapter implements AgentAdapter {
     return buildClaudeConfigSeed(root);
   }
 
+  // The repository's own settings files outrank what the session's user
+  // settings hold, so a launch behind impd's broker reads them first.
+  planProjectSettingsCheck(): ProjectSettingsCheck {
+    return buildClaudeProjectSettingsCheck(this.id);
+  }
+
   // A settings file of the session's own per binding revision carries the
   // placeholder, and so does the CLI's environment. The configured
   // arguments go without a permission mode, so the mode the session's own
@@ -232,7 +241,11 @@ export class ClaudeAdapter implements AgentAdapter {
   // config bundle, come from the host's own Claude config folder as it is
   // at this launch, staged under a key of this launch's own. A credential, endpoint, or provider variable in the
   // configured settings, or in the host's environment, would keep the CLI
-  // from sending the placeholder, so either refuses the start.
+  // from sending the placeholder, so either refuses the start. The entry's
+  // MCP servers reach the CLI through an MCP config file of the binding
+  // revision, each with the placeholder in its header. Their flag sits
+  // ahead of the settings flag, so the variadic flag never takes the
+  // prompt as one of its values.
   private planSubscriptionGuestSpawn(
     opts: SpawnOptions,
     dir: string,
@@ -247,6 +260,9 @@ export class ClaudeAdapter implements AgentAdapter {
     }
 
     const settingsPath = `auth-r${auth.revision}/settings.json`;
+    const mcpServers = this.entry.mcpServers ?? [];
+    const mcpPath = `auth-r${auth.revision}/mcp.json`;
+    const mcpArgs = mcpServers.length === 0 ? [] : ['--mcp-config', `${dir}/${mcpPath}`];
     const bundleKey = randomUUID();
 
     const launch = buildClaudeGuestLaunch(
@@ -256,7 +272,7 @@ export class ClaudeAdapter implements AgentAdapter {
         ...this.buildArgs(
           buildArgsWithoutFlags(this.entry.args, ['--permission-mode']),
           opts,
-          [],
+          mcpArgs,
           `${dir}/${settingsPath}`,
           `${dir}/atc-bridge`,
         ),
@@ -284,6 +300,9 @@ export class ClaudeAdapter implements AgentAdapter {
       args: launch.args,
       files: {
         [settingsPath]: JSON.stringify(settings, null, 2),
+        ...(mcpServers.length === 0
+          ? {}
+          : { [mcpPath]: JSON.stringify(buildClaudeMCPConfig(mcpServers), null, 2) }),
         ...buildClaudeConfigSeed(null),
         ...Object.fromEntries(
           Object.entries(bundle).map(([path, content]) => [
@@ -365,13 +384,13 @@ export class ClaudeAdapter implements AgentAdapter {
   private buildArgs(
     configured: readonly string[],
     opts: SpawnOptions,
-    modeArgs: readonly string[],
+    leadArgs: readonly string[],
     settings: string,
     pluginDir: string,
   ): string[] {
     return [
       ...buildClaudeOverrideArgs(configured, opts),
-      ...modeArgs,
+      ...leadArgs,
       '--settings',
       settings,
       '--plugin-dir',

package/src/agents/gateway-adapter.ts

@@ -17,6 +17,7 @@ import type {
   GuestSpawnPlan,
   HeadlessRunner,
   NameUpdate,
+  ProjectSettingsCheck,
   ResumeCheck,
   SpawnOptionSpecs,
   SpawnOptions,
@@ -26,6 +27,7 @@ import { buildATCBridgeFiles } from './build-atc-bridge-files';
 import { buildClaudeConfigSeed } from './build-claude-config-seed';
 import { buildClaudeGuestLaunch } from './build-claude-guest-launch';
 import { buildClaudeOverrideArgs } from './build-claude-override-args';
+import { buildClaudeProjectSettingsCheck } from './build-claude-project-settings-check';
 import { buildHookSettings } from './build-hook-settings';
 import { buildRestoreModeArgs } from './build-restore-mode-args';
 import { ClaudeAdapter } from './claude-adapter';
@@ -335,6 +337,12 @@ export class GatewayAdapter implements AgentAdapter {
     ];
   }
 
+  // The repository's own settings files reach the CLI as well, so a launch
+  // behind impd's broker reads them first.
+  planProjectSettingsCheck(): ProjectSettingsCheck {
+    return buildClaudeProjectSettingsCheck(this.id);
+  }
+
   private buildBrokerRefusal(reason: string): DaemonError {
     return new DaemonError(
       'auth_target_unsupported',

package/src/build-migrated-config.ts

@@ -113,10 +113,22 @@ function renderAgentEntry(entry: AgentEntry): Record<string, unknown> {
   }
 
   if (entry.auth !== undefined) {
-    rendered['auth'] =
-      Object.keys(entry.auth.placeholderEnv).length > 0
-        ? { profiles: entry.auth.profiles, placeholderEnv: entry.auth.placeholderEnv }
-        : { profiles: entry.auth.profiles };
+    rendered['auth'] = {
+      profiles: entry.auth.profiles,
+      ...(Object.keys(entry.auth.placeholderEnv).length > 0
+        ? { placeholderEnv: entry.auth.placeholderEnv }
+        : {}),
+      ...(entry.mcpServers === undefined
+        ? {}
+        : {
+            mcpServers: Object.fromEntries(
+              entry.mcpServers.map((server) => [
+                server.name,
+                { url: server.url, profile: server.profile },
+              ]),
+            ),
+          }),
+    };
   }
 
   return rendered;

package/src/daemon/sessions.ts

@@ -27,6 +27,7 @@ import { truncateDetail } from '../shared/truncate-detail';
 import { truncateToBytes } from '../shared/truncate-to-bytes';
 import type { FleetEntry, FleetEntryUpdate, FleetStore } from '../store/fleet-entry';
 import type { SessionWorkspace } from '../store/workspace-materialization';
+import { REPOSITORY_ENV_VARS } from '../workspace/repository-env-vars';
 import type { BrokerAuthHost } from './broker-auth-host';
 import { buildAuthBinding } from './build-auth-binding';
 import type { AuthBinding } from './build-auth-binding';
@@ -241,6 +242,31 @@ const RESOLVE_DIR_SCRIPT = `p=$1; s=; while [ ! -d "$p" ]; do s=/\${p##*/}$s; p=
 const REMOVE_DIR_SCRIPT =
   'cd -P -- "$1" || exit 3; [ "$(pwd -P; printf x)" = "$2" ] || exit 4; find . -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + || exit 5; cd / && rmdir -- "$1"';
 
+// Enters a directory as the host resolves it and prints, each followed by
+// a NUL, every path where something, even a dangling symlink, stands: each
+// start file in that directory, then each root file in that directory,
+// every directory above it, and the main checkout of the git worktree it
+// lies in. A `--` argument ends the start files. A directory that does not
+// exist exits with the absent status.
+const FIND_PROJECT_SETTINGS_SCRIPT = `cd -P -- "$1" 2>/dev/null || exit 3; shift; d=$(pwd -P)
+emit() { if [ -e "$1" ] || [ -L "$1" ]; then printf '%s\\0' "$1"; fi; }
+while [ "$#" -gt 0 ] && [ "$1" != -- ]; do emit "\${d%/}/$1"; shift; done; [ "$#" -gt 0 ] && shift
+m=$(git -c safe.directory='*' -c core.fsmonitor=false rev-parse --path-format=absolute --git-common-dir 2>/dev/null) && m=\${m%/.git} || m=
+for n in "$@"; do p=$d; while :; do emit "\${p%/}/$n"; [ "$p" = / ] && break; p=\${p%/*}; [ -n "$p" ] || p=/; done; [ -z "$m" ] || emit "\${m%/}/$n"; done
+exit 0`;
+
+// Prints at most one byte more than the largest project settings file atc
+// reads, following a symlink, and fails with the special-file status for
+// anything but a regular file there, such as a FIFO or a device that would
+// never end.
+const READ_SETTINGS_FILE = '[ -f "$1" ] || exit 4; exec head -c 1048577 -- "$1"';
+const ABSENT_DIR_EXIT = 3;
+
+// Runs git on the directory it starts in, whatever repository the daemon's
+// environment pins git to.
+const GIT_ENV_ARGV = ['env', ...[...REPOSITORY_ENV_VARS].flatMap((name) => ['-u', name])];
+const MAX_SETTINGS_BYTES = 1_048_576;
+
 // A readied host's harness plan, and the auth attempt that provisioned the
 // host, if one did.
 interface HarnessSetup {
@@ -693,6 +719,7 @@ export class SessionManager {
           ...(s.effort === undefined ? {} : { effort: s.effort }),
         },
         authSetup,
+        s.cwd,
       );
 
       plan = setup.plan;
@@ -999,6 +1026,10 @@ export class SessionManager {
       }
     }
 
+    // A spawn that builds its workspace reads the workspace's project
+    // settings once it is built, not when the host is readied before it.
+    const startDir = materialize === null ? cwd : null;
+
     const setupHost = () =>
       this.setupHarnessOnHost(
         adapter,
@@ -1008,9 +1039,17 @@ export class SessionManager {
         target,
         { prompt, resume, ...overrides },
         authSetup,
+        startDir,
         hostKey === id,
       );
 
+    // A launch behind the broker reads the project settings of the clone it
+    // starts in, once the clone is on the host and before it is trusted.
+    const checkWorkspace =
+      auth === null
+        ? null
+        : (root: string) => this.requireProjectSettings(adapter, provider, hostKey, target, root);
+
     // Takes back trust a spawn accepted in the user's own agent config when
     // the spawn fails before its harness starts.
     const localTrust: { remove: (() => Promise<void>) | null } = { remove: null };
@@ -1061,6 +1100,7 @@ export class SessionManager {
         execution.identity,
         materialize,
         setupHost,
+        checkWorkspace,
         trustWorkspace,
       );
     });
@@ -1591,7 +1631,9 @@ export class SessionManager {
   // Materializes a spawn's workspace, readying its host once the source
   // resolves, or after the workspace for a directory that runs as it
   // stands, and returns the directory it created, null for one that runs
-  // as it stands. A failure once the host is ready takes it back.
+  // as it stands. A clone is checked and then trusted, either as the caller
+  // asks, and a failure there removes it. A failure once the host is ready
+  // takes it back.
   private async materializeOnSpawnHost(
     provider: ExecutionProvider,
     id: SessionID,
@@ -1601,6 +1643,7 @@ export class SessionManager {
     targetIdentity: string,
     materialize: SpawnMaterializer,
     setupHost: () => Promise<HarnessSetup>,
+    checkWorkspace: ((root: string) => Promise<void>) | null,
     trustWorkspace: ((root: string) => Promise<void>) | null,
   ): Promise<{
     readonly setup: HarnessSetup;
@@ -1644,16 +1687,17 @@ export class SessionManager {
 
       readied.setup ??= await setupHost();
 
-      if (trustWorkspace !== null) {
-        if (materialized === null || readied.root === null) {
-          throw new DaemonError(
-            'bad_args',
-            'trustClonedWorkspace requires a successfully cloned workspace',
-          );
-        }
+      if (trustWorkspace !== null && (materialized === null || readied.root === null)) {
+        throw new DaemonError(
+          'bad_args',
+          'trustClonedWorkspace requires a successfully cloned workspace',
+        );
+      }
 
+      if (materialized !== null && readied.root !== null) {
         try {
-          await trustWorkspace(readied.root);
+          await checkWorkspace?.(readied.root);
+          await trustWorkspace?.(readied.root);
         } catch (error) {
           let removed = false;
 
@@ -1665,7 +1709,7 @@ export class SessionManager {
 
           if (!removed) {
             throw new EffectRemainsError(
-              'workspace trust setup failed and its clone could not be removed',
+              'workspace setup failed and its clone could not be removed',
               { cause: error },
             );
           }
@@ -1906,9 +1950,10 @@ export class SessionManager {
     target: string,
     options: SpawnOptions,
     auth: HarnessAuthSetup | null,
+    dir: string,
   ): Promise<{ readonly plan: HarnessPlan; readonly attemptID: string | null }> {
     return this.withHostReadying(hostKey, () =>
-      this.setupHarnessOnHost(adapter, provider, id, hostKey, target, options, auth, false),
+      this.setupHarnessOnHost(adapter, provider, id, hostKey, target, options, auth, dir, false),
     );
   }
 
@@ -1938,6 +1983,11 @@ export class SessionManager {
     options: SpawnOptions,
     auth: HarnessAuthSetup | null,
 
+    // The directory the harness starts in, whose project settings a launch
+    // behind the broker reads once the host is ready; null for a spawn
+    // whose workspace is built after this, which reads them once it is.
+    cwd: string | null,
+
     // Whether the host is a spawn's new host of its own, which a failure
     // once it is readied destroys.
     isNewHost: boolean,
@@ -2000,6 +2050,10 @@ export class SessionManager {
 
     try {
       await this.setupGuest(adapter, provider, hostKey, target, dir, plan.files);
+
+      if (auth !== null && cwd !== null) {
+        await this.requireProjectSettings(adapter, provider, hostKey, target, cwd);
+      }
     } catch (error) {
       if (attemptID !== null || isNewHost) {
         await this.destroyFailedSpawnHost(provider, id, hostKey, attemptID);
@@ -2135,6 +2189,84 @@ export class SessionManager {
     }
   }
 
+  // Reads each project settings file the agent applies for a harness behind
+  // the broker, from the directory it starts in as the host resolves it, and
+  // throws the agent's refusal for one that would override its sign-in. An
+  // absent file passes; one the host holds but cannot read, that is not a
+  // regular file, or that is larger than any settings file refuses, since
+  // what the agent would take from it is unknown. A relative directory is
+  // under the host's home.
+  private async requireProjectSettings(
+    adapter: AgentAdapter,
+    provider: ExecutionProvider,
+    hostKey: SessionID,
+    target: string,
+    cwd: string,
+  ): Promise<void> {
+    const check = adapter.planProjectSettingsCheck?.();
+
+    if (check === undefined) {
+      return;
+    }
+
+    // The host resolves the directory as given, since a lexical join would
+    // drop a parent step after a symlink that the host follows.
+    const home = posix.isAbsolute(cwd) ? null : await this.resolveHostHome(provider, hostKey);
+    const dir = home === null ? cwd : `${home}/${cwd}`;
+
+    const found = await provider.runCommand({
+      argv: [
+        ...GIT_ENV_ARGV,
+        'sh',
+        '-c',
+        FIND_PROJECT_SETTINGS_SCRIPT,
+        'sh',
+        dir,
+        ...check.files,
+        '--',
+        ...check.rootFiles,
+      ],
+      cwd: '/',
+      host: hostKey,
+    });
+
+    if (found.exitCode === ABSENT_DIR_EXIT) {
+      return;
+    }
+
+    if (found.exitCode !== 0) {
+      throw this.buildUnreadableSettingsRefusal(adapter.id, target, dir);
+    }
+
+    const paths = new Set(found.stdout.split('\0').filter((path) => path !== ''));
+
+    for (const path of paths) {
+      const read = await provider.runCommand({
+        argv: ['sh', '-c', READ_SETTINGS_FILE, 'sh', path],
+        cwd: '/',
+        host: hostKey,
+      });
+
+      if (read.exitCode !== 0 || Buffer.byteLength(read.stdout) > MAX_SETTINGS_BYTES) {
+        throw this.buildUnreadableSettingsRefusal(adapter.id, target, path);
+      }
+
+      const refusal = check.findRefusal(path, read.stdout);
+
+      if (refusal !== null) {
+        throw new DaemonError(refusal.code, refusal.message, { ...refusal.data, target });
+      }
+    }
+  }
+
+  private buildUnreadableSettingsRefusal(agent: string, target: string, path: string): DaemonError {
+    return new DaemonError(
+      'auth_target_unsupported',
+      `agent '${agent}' signs in through impd's broker on target '${target}', but atc cannot read ${path} there as a settings file to check it for settings that would override that sign-in`,
+      { agent, target, problem: 'project_settings_unreadable', file: path },
+    );
+  }
+
   // A sub-session runs on its parent's host when its resolved target, name
   // and identity both, is the one its parent is bound to and that target's
   // hosts have a lifecycle, so one host serves a top-level session and

package/src/shared/collect-agents.ts

@@ -3,6 +3,7 @@ import { checkGatewayAuth } from './check-gateway-auth';
 import type { GatewayAuth } from './check-gateway-auth';
 import type { AuthProfile } from './collect-auth-profiles';
 import { collectClaudeAuth } from './collect-claude-auth';
+import type { ClaudeMCPServer } from './collect-claude-auth';
 import { isSubscriptionOverrideVariable } from './is-subscription-override-variable';
 import { isRecord } from './report';
 
@@ -16,7 +17,8 @@ type AgentKind = 'claude' | 'codex' | 'grok';
  * and arguments it starts with, and, for a Claude entry, the settings, the
  * environment, and the backend and credential it runs against. A Claude entry
  * with a `baseURL` is a gateway; without one it is stock Claude, whose
- * `auth` holds profiles alone, for the subscription sign-in.
+ * `auth` holds profiles alone, for the subscription sign-in, and whose
+ * `mcpServers` reach their hosts through those profiles.
  */
 export interface AgentEntry {
   readonly id: AgentID;
@@ -30,6 +32,7 @@ export interface AgentEntry {
   readonly baseURL?: string;
   readonly apiKeyHelper?: string;
   readonly auth?: GatewayAuth;
+  readonly mcpServers?: readonly ClaudeMCPServer[];
 }
 
 interface CollectedAgents {
@@ -43,7 +46,8 @@ interface CollectedAgents {
  * Reads the `agents` map into registry order. An entry that is not an object,
  * sets an unknown field or a field outside its kind, holds a wrong-typed
  * value, or fails an auth check is left out with every problem that refused
- * it, and the other entries load. A value that is not an object leaves the
+ * it, and the other entries load. An MCP server that breaks a rule is left
+ * out of its entry with an error, and the entry loads. A value that is not an object leaves the
  * registry empty.
  */
 export function collectAgents(
@@ -64,6 +68,7 @@ export function collectAgents(
       errors.push(...parsed.problems.map((problem) => `agents.${id}: ${problem}`));
     } else {
       agents.push(parsed.entry);
+      errors.push(...(parsed.warnings ?? []).map((warning) => `agents.${id}: ${warning}`));
     }
   }
 
@@ -86,7 +91,9 @@ const DEFAULT_LABELS: Readonly<Record<AgentKind, string>> = {
   grok: 'Grok',
 };
 
-type ParsedEntry = { readonly entry: AgentEntry } | { readonly problems: string[] };
+type ParsedEntry =
+  | { readonly entry: AgentEntry; readonly warnings?: readonly string[] }
+  | { readonly problems: string[] };
 
 function parseAgentEntry(
   id: string,
@@ -125,7 +132,9 @@ function parseAgentEntry(
     return claude;
   }
 
-  return { entry: { ...entry, ...claude } };
+  const { warnings, ...read } = claude;
+
+  return { entry: { ...entry, ...read }, ...(warnings === undefined ? {} : { warnings }) };
 }
 
 // The entry's kind, or the problem that refuses it. An absent kind is the id
@@ -251,6 +260,12 @@ function buildDefaultLabel(id: string, kind: AgentKind): string {
   return id === kind ? DEFAULT_LABELS[kind] : id;
 }
 
+interface ReadClaudeAuth {
+  readonly auth?: GatewayAuth;
+  readonly mcpServers?: readonly ClaudeMCPServer[];
+  readonly warnings?: readonly string[];
+}
+
 // The `auth` a Claude entry holds, or every problem with it. With a base URL
 // the entry is a gateway and its auth is the gateway's. Without one it is
 // stock Claude, whose auth is profiles alone and whose environment may not
@@ -259,7 +274,7 @@ function readClaudeAuth(
   entry: AgentEntry,
   raw: unknown,
   authProfiles: ReadonlyMap<string, AuthProfile>,
-): { readonly auth?: GatewayAuth } | { readonly problems: string[] } {
+): ReadClaudeAuth | { readonly problems: string[] } {
   if (entry.baseURL !== undefined) {
     if (raw === undefined) {
       return {};
@@ -288,13 +303,21 @@ function readClaudeAuth(
 
   const collected = collectClaudeAuth(raw, authProfiles, 'auth');
 
-  problems.push(...collected.errors, ...collectSubscriptionProblems(entry));
+  problems.push(...collectSubscriptionProblems(entry));
 
-  if (problems.length > 0 || collected.auth === null) {
+  if (collected.auth === null) {
+    return { problems: [...collected.errors, ...problems] };
+  }
+
+  if (problems.length > 0) {
     return { problems };
   }
 
-  return { auth: { profiles: collected.auth.profiles, placeholderEnv: {} } };
+  return {
+    auth: { profiles: collected.auth.profiles, placeholderEnv: {} },
+    ...(collected.auth.mcpServers.length === 0 ? {} : { mcpServers: collected.auth.mcpServers }),
+    warnings: collected.errors,
+  };
 }
 
 // What a stock entry with `auth` sets that would override the subscription

package/src/shared/collect-claude-auth.ts

@@ -2,14 +2,28 @@ import type { AuthProfile } from './collect-auth-profiles';
 import { isRecord } from './report';
 import { resolveAuthProfiles } from './resolve-auth-profiles';
 
+/**
+ * An MCP server a stock Claude session on a target that reaches impd's
+ * broker reaches over HTTP, with the header that one of the session's
+ * profiles sets for the server's host. The session sends a placeholder in
+ * that header, and impd swaps the credential in on the host's side.
+ */
+export interface ClaudeMCPServer {
+  readonly name: string;
+  readonly url: string;
+  readonly profile: string;
+  readonly header: string;
+}
+
 /**
  * The profiles a stock Claude session on a target that reaches impd's
  * broker signs in through: one of them sends the subscription's setup
  * token to the Anthropic API as a bearer authorization header, and the
- * rest bind beside it, such as a GitHub token.
+ * rest bind beside it, such as a GitHub token or an MCP server's key.
  */
 interface ClaudeAuth {
   readonly profiles: readonly string[];
+  readonly mcpServers: readonly ClaudeMCPServer[];
 }
 
 interface CollectedClaudeAuth {
@@ -23,7 +37,8 @@ interface CollectedClaudeAuth {
  * does not resolve, or whose profiles send no bearer authorization header
  * to the Anthropic API, is left out with every problem that refused it, so
  * stock Claude keeps the sign-in of the host it runs on rather than binding
- * a credential the CLI would never send.
+ * a credential the CLI would never send. An MCP server that breaks a rule
+ * is left out alone, with an error, and the sign-in stays.
  */
 export function collectClaudeAuth(
   raw: unknown,
@@ -48,7 +63,7 @@ export function collectClaudeAuth(
     };
   }
 
-  const extra = Object.keys(raw).find((key) => key !== 'profiles');
+  const extra = Object.keys(raw).find((key) => key !== 'profiles' && key !== 'mcpServers');
 
   if (extra !== undefined) {
     return {
@@ -79,8 +94,106 @@ export function collectClaudeAuth(
     };
   }
 
-  return { auth: { profiles: selected }, errors: [] };
+  const servers = collectMCPServers(raw['mcpServers'], field, selected, authProfiles);
+
+  return { auth: { profiles: selected, mcpServers: servers.servers }, errors: servers.errors };
 }
 
 // The one host Claude Code sends a subscription token to.
 const ANTHROPIC_API_HOST = 'api.anthropic.com';
+
+interface CollectedMCPServers {
+  readonly servers: readonly ClaudeMCPServer[];
+  readonly errors: readonly string[];
+}
+
+// Reads the `mcpServers` map, server names to the server's URL and the
+// selected profile that carries its credential.
+function collectMCPServers(
+  raw: unknown,
+  field: string,
+  selected: readonly string[],
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): CollectedMCPServers {
+  if (raw === undefined) {
+    return { servers: [], errors: [] };
+  }
+
+  if (!isRecord(raw) || Array.isArray(raw)) {
+    return { servers: [], errors: [`${field}.mcpServers must be an object of named servers`] };
+  }
+
+  const servers: ClaudeMCPServer[] = [];
+  const errors: string[] = [];
+
+  for (const [name, entry] of Object.entries(raw)) {
+    const parsed = parseMCPServer(name, entry, field, selected, authProfiles);
+
+    if (typeof parsed === 'string') {
+      errors.push(`${field}.mcpServers.${name}: ${parsed}`);
+    } else {
+      servers.push(parsed);
+    }
+  }
+
+  return { servers, errors };
+}
+
+// Claude Code's rule for an MCP server's name.
+const MCP_SERVER_NAME = /^[\w-]{1,64}$/u;
+
+// The server an entry holds, or the first rule it breaks. The header comes
+// from the profile, so the header the session sends and the one impd swaps
+// the credential into never differ.
+function parseMCPServer(
+  name: string,
+  entry: unknown,
+  field: string,
+  selected: readonly string[],
+  authProfiles: ReadonlyMap<string, AuthProfile>,
+): ClaudeMCPServer | string {
+  if (!MCP_SERVER_NAME.test(name)) {
+    return 'a server name must be letters, digits, underscores or hyphens';
+  }
+
+  if (!isRecord(entry) || Array.isArray(entry)) {
+    return 'a server must be an object with url and profile';
+  }
+
+  const extra = Object.keys(entry).find((key) => key !== 'url' && key !== 'profile');
+
+  if (extra !== undefined) {
+    return `${extra} cannot be set: atc fixes the transport and the placeholder header`;
+  }
+
+  const url = entry['url'];
+  const profileName = entry['profile'];
+
+  if (typeof profileName !== 'string' || !selected.includes(profileName)) {
+    return `profile must be one of ${field}.profiles`;
+  }
+
+  const profile = authProfiles.get(profileName);
+
+  if (profile?.kind !== 'custom') {
+    return 'profile must be a custom profile, which sets one header for one host';
+  }
+
+  const parsedURL = typeof url === 'string' && URL.canParse(url) ? new URL(url) : null;
+
+  if (
+    parsedURL === null ||
+    parsedURL.protocol !== 'https:' ||
+    parsedURL.port !== '' ||
+    parsedURL.username !== '' ||
+    parsedURL.password !== ''
+  ) {
+    return 'url must be an https URL with no port and no user info';
+  }
+
+  if (parsedURL.hostname !== profile.host) {
+    return `url must be on ${profile.host}, the host profile ${profileName} sends its credential to`;
+  }
+
+  return { name, url: parsedURL.href, profile: profileName, header: profile.header };
+}

package/src/shared/collect-legacy-agents.ts

@@ -51,6 +51,9 @@ export function collectLegacyAgents(
       ...(claudeAuth.auth === null
         ? {}
         : { auth: { profiles: claudeAuth.auth.profiles, placeholderEnv: {} } }),
+      ...(claudeAuth.auth === null || claudeAuth.auth.mcpServers.length === 0
+        ? {}
+        : { mcpServers: claudeAuth.auth.mcpServers }),
     },
     {
       id: 'grok',