feat(server): claude.mcpServers — your own MCP servers can reach Paddock's agents (#691)

[edspencer]

Step 5 of #691 — the last of the five levers.

claude:
  transcripts:  own    # own | host
  credentials:  host   # own | host
  instructions: own    # own | host
  hooks:        own    # own | host
  mcpServers:   own    # own | host  ← this PR

host attaches the servers declared in the user's ~/.claude.json: the top-level mcpServers (user scope, every project) plus projects.<absolute-dir>.mcpServers, which a project gets only when that directory is its own working directory. own is the default. Also PADDOCK_CLAUDE_MCP_SERVERS, env > file > default. Under own the file is never opened.

Why this key is not a symlink like the other four

MCP servers are not inside ~/.claude at all. Claude Code resolves them from join(CLAUDE_CONFIG_DIR ?? homedir(), ".claude.json") — a sibling of the home. Read straight out of the SDK bundle, where the two paths sit one expression apart and disagree:

let d = CLAUDE_CONFIG_DIR,
    f = d ?? join(homedir(), ".claude");        // .credentials.json lives under here
… readFile(join(f, ".credentials.json"))
… copy(join(d ?? homedir(), ".claude.json"), …) // ← homedir, NOT ~/.claude

So once Paddock owns its home, no bridge of entries inside the home could ever have reached it. That is why MCP inheritance broke silently and separately from everything else. host is therefore a read: Paddock reads that file once at boot and passes the servers programmatically. It deliberately does not symlink it — Claude Code writes per-project trust, approvals and migration flags there, and bridging it would mean a Paddock instance mutating the user's real config.

Three things that contradict #691

1. "Paddock sets none today" is false, and the seam is a different one. #691 says to pass servers via herdctl's runner option SDKQueryOptions.mcpServers. But SDKQueryOptions is built by herdctl (toSDKOptions), never by Paddock, and its mcpServers is populated from transformMcpServers(agent.mcp_servers) — the agent config. Paddock already sets that key: browserMcpServers (#269) puts the headless-Chromium stdio server there on every keeper and trigger.

That makes the work smaller. agent.mcp_servers is the one seam covering both runtimes — the SDK adapter turns it into sdkOptions.mcpServers (and buildSdkOptions is shared by execute and openSession, so live chats included), and the CLI runtime serialises the same record into --mcp-config '{"mcpServers":…}'. The runner option would have covered one.

2. The allowlist would have made this a silent no-op. Paddock's fleet defaults carry an explicit allowed_tools, and both runtimes auto-deny any tool absent from it, with no prompt — the lesson Skill taught. MCP tools are mcp__<server>__<tool>. herdctl auto-adds those patterns for injected servers only (cli-runtime.js: "only needed when the agent has an explicit allowlist"); config mcp_servers get nothing, which is exactly why mcp__playwright__* is hard-coded into the defaults.

So a keeper with host servers restates FLEET_ALLOWED_TOOLS (extracted for this — herdctl's mergeAgentConfig replaces arrays rather than merging) plus one pattern per server. Without it the lever would have shipped looking correct: servers attached, every call refused, nothing in the logs.

3. The plugins arm is blocked, and not for the reason #691 gives. #691 says "the SDK does not auto-discover installed plugins; the interactive CLI does". It does auto-discover them — the plugin root is join(CLAUDE_CONFIG_DIR, "plugins"), the plugins option is merged with what is found there, and a live probe in step 4 loaded a plugin from a planted home with no option passed. What actually blocks it is two other things:

• discovery is gated on enabledPlugins, which lives in settings.json's userSettings source, and herdctl invokes the SDK with --setting-sources=project for every agent with a working directory — so the flag is never read;
• herdctl has no plugins passthrough at all. SDKQueryOptions has no such field and toSDKOptions never sets one (one plugins hit in the whole of dist/, and it is a comment).

So there is no channel to write to. I did not ship an enumerator that nothing can consume — see "What I deliberately did not do".

Open question answered: MCP OAuth tokens do follow claude.credentials

From the bundled CLI binary, not inferred. Tokens are stored under a top-level mcpOAuth key in the same credential store as claudeAiOauth — <securestorage-dir>/.credentials.json, or the one Claude Code-credentials keychain item. There is no MCP-specific service name and no separate token file. The store resolves from CLAUDE_SECURESTORAGE_CONFIG_DIR ?? CLAUDE_CONFIG_DIR ?? ~/.claude, which is precisely the variable claude.credentials drives.

So credentials: host carries MCP tokens, and they are not separable from the Anthropic login in either direction. credentials: own means re-authorising inside Paddock (mcpAuthenticate exists for that).

With one sharp edge: the per-server key is `${name}|${sha256({type,url,headers}).slice(0,16)}`.

What cannot be carried, and is warned about rather than hidden

herdctl's McpServerSchema is {command?, args?, env?, url?} — a plain z.object, so anything else is stripped at addAgent. Two consequences #691 does not mention, made worse by that hash:

Dropped	Effect
headers	bearer auth is lost — and the OAuth token, keyed on a hash including the headers, is not found either
type: "sse"	transformMcpServer maps every url to type: "http"; same hash problem

Both need a herdctl schema change. What Paddock does here is refuse to be silent: each affected server is named in a warn at boot. The server is still passed — this is a capability lever, not a security one, so a user who declared a server gets it plus a warning rather than nothing plus a warning. The only case actually dropped is a server with neither command nor url, which cannot be started at all.

Tests

Server 1779 → 1813 (+34, +3 files), web 941 unchanged. Every fixture synthetic; no real ~/.claude.json is read anywhere.

The one that matters is test/unit/herdctl-host-mcp.test.ts → "hands the runtime nothing under own and the user's servers under host": it asserts on the agent config, which is what both runtimes read their MCP servers from, and pins that nothing else about the agent moves between the two modes. Alongside it, "widens the allowlist by each host server's tool pattern, or they are all denied" is the one that would have caught finding 2.

The per-directory scope is covered twice — mcpServersFor (exact match, no parent walk, so Paddock's answer equals the terminal's) and end-to-end through a real buildApp() boot in test/integration/claude-mcp-servers.test.ts, which also proves the file is read from beside the throwaway HOME and not read at all under own.

Deliberately not done

• The plugins arm — blocked upstream (above), and an enumerator with no consumer is dead code. Two routes exist for whoever picks it up: a plugins passthrough in herdctl, or widening setting_sources to include user so the already-bridged plugins/ dir and the already-preserved enabledPlugins key start working together. The second needs no herdctl change but would also start loading the home's permissions, model and — under hooks: host — its hooks on the SDK path, which is a security decision well outside this brief and adjacent to claude.hooks: own stops hooks, not host commands — nine other settings.json keys name a command to run #698. Unverified either way: zero plugins are installed on this box, so the disk-layout claims come from reading the binary, not from observing one. (Marketplace installs land at <root>/cache/<marketplace>/<plugin>/<version>/, not the repos/ layout the brief predicted, and a strict: false marketplace entry may have no plugin.json on disk at all — so "local only is probably not a blocker" is mostly right with an exception.)
• Step 6 (an instance-level mcpServers: block) — out of scope by the brief. Built so it is an addition: everything below the parse is source-agnostic, and step 6 adds a second contributor to HostMcpSource.user.
• claude.hooks: own stops hooks, not host commands — nine other settings.json keys name a command to run #698 (widening HOST_ONLY_SETTINGS_KEYS) and A chat deleted in a Claude home Paddock doesn't own is released but still listed #693's tombstone — out of scope.
• Triggers and the sweeper get no host servers. The sweeper is tool-less; each trigger declares its own narrow allowlist. Attaching servers to either would spawn a stdio process per fire that nothing could call. Asserted, not assumed.
• A file-watcher on ~/.claude.json. Read once at boot, like claude.hooks materialises settings.json; restart to pick up a new server, and the notice says so.
• Anything requiring a live MCP server, macOS, or real credentials — none exist here. Nothing in this PR starts a server or calls a tool; an agent config is data until a turn runs.

One thing that could not be verified locally: npm run typecheck fails on reapChatSession in herdctl.ts — @herdctl/core@5.29.1 installed against a declared ^5.31.0. It is present on main untouched, and it also means local E2E cannot run. CI installs fresh.

Closes the mcpServers row of #691.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying paddock with    Cloudflare Pages

Latest commit:	a71703f
Status:	✅  Deploy successful!
Preview URL:	https://55dcb1e6.paddock-7u2.pages.dev
Branch Preview URL:	https://feat-691-mcp-servers.paddock-7u2.pages.dev

View logs