Repository navigation
feat(server): Claude threads apply their MCP profile's outside servers - #528
scuttletoby wants to merge 5 commits into
Conversation
MCP profiles part 2. A Claude thread's profile now reaches its session: t3-only and an empty server list open Claude in strict MCP mode, and a named list passes an allowlist of those servers (plus T3's own). A profile that cannot be applied refuses the turn with a message that says why and how to fix it, and a started session that still shows a server the profile leaves out is closed and refused. With no profile set, nothing changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Keep main's prepare-server-compile-cache.cjs seam entry and add this PR's three entries. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review (independent, Opus)Reviewed head Verdict: no blocking findings. I found no path where a thread opens a Claude process with more outside servers than its profile allows (the remote-parent case below is a documented rule, not a leak). No path swallows a refusal. Checked and fine
Findings (most severe first)
State question summary
|
Review (independent, Opus)Reviewed head Verdict: no blocking findings. The main path is sound:
Two findings are worth fixing first (1 and 2 below). 1. SHOULD-FIX: servers that start after the one-time check are never checked, which matters exactly when T3's allowlist is dropped
Per Scenario:
A similar case for Suggested fix: enforce at call time as well as at open. Add a 2. SHOULD-FIX: with no profile set, a failed settings read now refuses every Claude turn
Now a secret-store read error for an unrelated provider instance refuses every Claude thread with "could not read this thread's MCP profile settings", even for an owner who has never set a profile. That breaks "with no profile set, behaviour must be exactly as before". Suggested fix: the four MCP keys need no secrets, so read them from the unmaterialized settings (or an MCP-only accessor). Refuse only when that read fails. 3. SHOULD-FIX (owner decision; the PR flags it as decision 2): a remote parent is treated more loosely than a local one
A local child whose parent cannot be read is refused, which matches #101. A child delegated from another machine has Scenario: on machine B the owner has set Server names on two machines need not mean the same servers, so "use B's default" may be the right call. But it should be a stated choice in the docs. Also, the comment at 4. NIT: the live-query key relies on object identity and has no test
The plan's part of the key travels in a But if a future caller passes a copied or rebuilt overrides object, it silently gets the 5. NIT: the post-start status call has no timeout
When the thread has no T3 MCP session ( 6. NIT: more refusals than needed (not wider)
State question: checked and OK
Tests
|
…de-servers # Conflicts: # .github/fork-seams.json
Fix round for the two reviews of PR 528: - Call-time guard: a profile other than all adds a PreToolUse hook that refuses a tool call (or an MCP resource read) to a server outside the profile, in every permission mode and inside sub-agents. Covers a managed policy that drops T3's allowlist, agent-file servers and servers added mid-session. The adapter merges it into its own hooks (one seam line, announced in PR 533). - No-profile path: a failed settings read (it reads provider secrets too) refuses only when the settings last read had a profile set; otherwise the thread gets all, with a warning, as upstream's own reads fall back. - Reuse key: overrides with no worked-out plan get a key no other turn has, so a reordered or rebuilt key line opens a new process instead of reusing a wider one; a two-turn test locks reuse and replacement. - The start-time server check times out after 5 minutes and then refuses. - The leaked-server refusal names --mcp-config in the Claude launch arguments; a missing settings service is logged. - A task delegated from another machine keeps this machine's profile for its role: comment and docs say so; carrying the parent's profile is #532. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
) Announces one more ClaudeAdapterV2.ts line for MCP profiles part 2: the adapter merges the profile's PreToolUse hook (the call-time guard that refuses a tool call to a server outside the thread's profile) into its own hooks. Joins the existing announcement of 2026-11-19 and updates the entry's why. List only; #528 adds the line and moves it to "added". Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Why
PR 2 of the MCP profile design (#145): "Claude: outside servers". PR 1 (#227) added the settings and the pure resolver, but nothing called the resolver. With this PR a Claude thread's profile reaches its session. Per #101, a profile that cannot be applied refuses the turn and says why and how to fix it. It never starts the turn with every tool.
Depends on #533 (step 1 for the fix round's one new seam line; #527 merged and announced the first 12). A PR is judged by main's seam list, so this PR's seam check fails until #533 merges. After that, main needs merging in once more; the list conflict resolves to this PR's side.
Fix round (both reviews)
mcpServers, a server added mid-session)PreToolUsehook refuses, at the moment of the call, anymcp__<server>__…tool, andListMcpResourcesTool/ReadMcpResourceToolnaming a server outside the profile. It uses Claude'smcp_server.namewhen given, else the tool-name prefix, normalised as the CLI does (claude.ai Drive→claude_ai_Drive). Claude gets the reason as the call's result, and the turn goes on. Hooks run in every permission mode and inside sub-agents. Withallthere is no hook.getSettingsalso reads provider secrets, so an unrelated secret-store error blocked Claude.allwith a log warning, as upstream's own reads in the adapter do. It refuses (#101) only when the settings this adapter last read had something set that can narrow a profile.t3-onlylikeall, so a narrowed thread could reuse its wider process.mcpOverrides, and a PR may not change an upstream line (the seam check refuses lost lines), so the key cannot take the plan as an argument. Overrides with no worked-out plan now get a key no other turn has: a reorder opens a new process each turn and never reuses a wider one. A two-turn test locks both directions; with the lines reordered on purpose, it fails.--mcp-configin the Claude launch arguments too. A missing settings service logs a warning once.Guaranteed for a profile other than
all: no MCP tool call or resource read reaches a server the profile leaves out, whatever loaded it. A session that shows such a server at start, or does not list its servers within 5 minutes, never starts the turn. With no profile set, sessions open exactly as before: no hook, no status call, the same key, and no refusal from a failed settings read.Not guaranteed:
--mcp-configadds it; its calls are refused.allif nothing was set), with a warning.settings.jsonthat does not parse loads as defaults (upstream's rule), so its profiles do not apply until it is fixed; upstream logs that.mcp_serveris matched by tool-name prefix, so a server named likedocs__xpasses under a profile that namesdocs.What changes
apps/server/src/fork/claudeMcpProfile.ts(new, fork-owned) turns the resolver's result into a Claude plan:all: no new options. The session opens exactly as before.t3-onlyorservers: []:strictMcpConfig: true.managedSettings.allowedMcpServerswith the named servers plus T3's own (t3-code).ClaudeMcpProfileError, message shown in the thread) in these cases:t3Toolsis not"all", because nothing applies T3 tool groups until the T3 tool filter PR;alland a warning).PreToolUsehook refuses a call to a server outside the plan.mcpServerStatus). If any server is there that the plan leaves out (any status butdisabled), T3 closes the session and refuses the turn. This catches the cases T3's options cannot control:managedSettings;--mcp-configin the user's Claude launch arguments, which strict mode keeps;inherit). With no profile set, no thread is read.allthe key is byte-for-byte what it was.ClaudeAdapterV2.ts(11: the 13th merges the profile's hook into the adapter's hooks);ProviderTurnStartService.ts(1): the refusal counts as "refused before the prompt";failure.ts(1): the refusal's message is shown, not hidden as a generic error.docs/fork/README.md(server.mcpProfiles) and theFORK_CHANGES.mdrow.The 30-minute check
Read in SDK 0.3.321 (
sdk.d.ts), in the Claude Code 2.1.326 binary's code, and tried live. The live probe opened a session with no prompt sent (no API turn) andpersistSession: false, then readmcpServerStatus().1. Does
strictMcpConfigalso drop plugin servers and account connectors? Yes, both.claude.ai Claude Docs, 8 tools) is listed without strict and absent with strict. The CLI's own text for this case reads: "claude.ai connectors are not loaded in this Claude Code session (MCP servers are restricted to explicitly passed config here, e.g. --strict-mcp-config or --bare)"..mcp.json, user settings, plugins, and on-disk agent frontmatter". The CLI's plugin-server lookup returns an empty set under strict. I could not show this live: my throwaway local plugin's server did not load even without strict..mcp.json: dropped (observed live).t3-code, whichsetMcpServersadds after start; observed still registered under strict),--mcp-configservers, and servers declared inline in SDK-passedagentsdefinitions. T3 passes noagents. The--mcp-configcase is why the post-start check exists.allowedMcpServers: [t3probe, projsrv]kept exactly those two and dropped the claude.ai connector. Per the SDK, an IT-managed settings tier on the machine drops these parent-suppliedmanagedSettings; the post-start check turns that into a refusal.2. Is the visibility rule asked on
tools/callor only ontools/list? Both.McpServer.visibility(.repos/effect/packages/effect/src/ai/McpServer.ts), the check runs "on list requests and on calls, reads, gets and completions". When it returnsfalse, the tool is left out of lists, and a call fails as if the tool were not registered (notFound).layerDeferredListinginMcpHttpServer.ts, returnstruefor every method buttools/liston purpose ("Calls are never gated"). So the T3 tool filter (a later PR) gates calls for free, as long as its check does not short-circuit onmethod.Tool counts before and after (on one real machine)
The machine has one claude.ai connector (8 tools) and, for the probe, one project
.mcp.jsonserver. "Outside" means every MCP server except T3's own:all(before and after)claude.ai Claude Docst3-only(strict){ servers: ["projsrv"] }(allowlist)T3's own tools are unchanged by this PR; the
t3Toolsfilter comes later.Default behaviour is unchanged
claudeMcpProfile.adapter.test.tschecks the default case: with server settings that set no profile, the Claude session opens with neitherstrictMcpConfignormanagedSettings, and T3 never asks Claude for its servers (that stub dies if called). The other ~460 Claude adapter tests run without settings and pass unchanged. InclaudeMcpProfile.test.ts, "with no profile set, a child gets all and no parent is read" uses a store that dies on read.Tests: fail before, pass after
claudeMcpProfile.adapter.test.tsfails 4 of 5: t3-only strict, the allowlist, refusal of a missing profile, and refusal plus close on a leaked server. The default test passes both before and after, as it should.claudeMcpProfile.ts(stub exports added only so the new tests import), 7 tests fail: the call-time refusal (adapter), the leaked-server and resource rows of the guard table, the fail-closed key, the no-profile fallback on a failed read, and the status timeout. All pass now (76 in the three MCP profile files). The two-turn reuse test passes on both; it is the lock for the key, and fails when the key line is moved above the profile line.ClaudeAdapterV2.test.ts: 466 of 467. The one failure, "forks a session from its original directory…", is environmental: this machine's node lackslibatomic.so.1. It fails the same way onmain.vp run check:changed).Review: the state question
onErrorpath, the same cleanup as a failed open.all, so behaviour is unchanged.Decisions for reviewers
t3Toolsother than"all"refuses on Claude until the T3 tool filter lands. Following Owner question: when a thread's tool profile cannot be applied, refuse to start or start with all tools? #101 literally: starting with all T3 tools would quietly widen. Until then such profiles are usable on no Claude thread.parentThreadId: null). It gets this machine's role default (mcpSubagentProfile, elsemcpProfile), not its remote parent's profile. Kept in the fix round; the docs say so, and MCP profiles: carry the parent's profile with a cross-machine delegation #532 tracks carrying the parent's profile.Upstream fit
Fork-only feature, kept out of upstream's files except 12 added lines. Upstream has no MCP profile concept. If upstream adds per-thread MCP selection,
claudeMcpProfilePlanmaps onto it, and the seam lines go. The SDK features used (strictMcpConfig,managedSettings.allowedMcpServers,mcpServerStatus) are public SDK options.General vs project
General: any T3 user with MCP servers in their Claude config can limit what a thread sees, and nothing changes for anyone who sets no profile. Nothing here is specific to one project or machine; the names in the docs (
claude.ai Calendar) are examples.Claude Opus 5.5 in Claude Code (T3 Code harness).
🤖 Generated with Claude Code