Claude Code Subagent MCP: Folder Trust and Startup Controls

Inline MCP servers in a cloned repository’s .claude/agents/ do not start until you trust that folder. Claude Code added this check in v2.1.238, including for claude -p. After trust, they connect when the subagent starts, or at startup when selected as the main session with --agent. Read the files to inspect without starting them. --strict-mcp-config can suppress them, but explicit --agents definitions are an exception.

Checked: 2026-11-12 JST. Target: Claude Code 2.1.319 on macOS, Node.js v26.12.1. Official documents were retrieved the same day. We recorded whether a dummy MCP started in an unauthenticated isolated environment. Model calls, the interactive trust dialog, the SDK and older versions were not tested.

The key points concern where the definition comes from.

• Project and --add-dir inline definitions require trust of their own definition folder.
• Parent-folder trust and the automatic treatment of -p do not satisfy this check.
• User agents, explicit --agents input and references to configured server names do not use this folder-trust check.
• Do not treat --bare or a limited settings source as a guarantee that every MCP is stopped.

#Does opening a cloned repo start its subagent MCP?

Opening a folder and running an agent in Claude Code are different operations. The official Subagents documentation says inline MCP from project and --add-dir agent files loads only after trust of the definition folder. Our untrusted runs did not start it either.

This check does not stop all repository code. Settings hooks and .mcp.json, for example, follow different trust and approval rules. Inspect what could run before starting a session.

#What changed in v2.1.238?

Changelog 2.1.238, dated August 20, 2026, records the added check. Subagents also says earlier versions loaded these servers without checking trust. Applying that older behavior to a current untrusted folder would give the wrong answer. We tested only 2.1.319.

#Is claude -p or the SDK different?

The Permissions table says -p and SDK sessions never show the interactive trust dialog. They still do not bypass the trust required for project inline MCP. The SDK explanation is documentation only; our execution used claude -p.

#What starts after folder trust, and when?

The documentation connects inline servers when a subagent starts and disconnects them when it finishes. When selected as the main session with --agent, they connect at startup. A cached remote HTTP/SSE connection can instead wait until the first tool call. Our dummy used local stdio only.

#Is trusting the parent folder enough?

No. We separately synthesized no trust, parent-only trust and definition-folder trust. Project and --add-dir inline definitions started only in the last condition.

#What about a folder passed with --add-dir?

An additional directory outside the trusted workspace repository needs its own trust entry. A separate dummy folder produced that result in this run. Trust of the working folder is not permission for that additional source.

#Which sources do not wait for that folder trust?

This table uses no suppressor. “Official” describes the definition-folder trust rule; “observed” records only this run’s stdio startup. For the name reference we separately registered a .mcp.json server and ran -p.

The documentation also exempts inline agents supplied through managed settings from this folder-trust check. We did not test managed settings. Exemption from this check does not disable other policies.

Distinguish .mcp.json approval, covered in Claude Code MCP configuration and scopes.

The interactive and mcp list descriptions are from the documentation. Read files instead of running claude mcp list when inspection must avoid communication.

#How can I inspect without starting servers?

Read mcpServers in the frontmatter at the start of .claude/agents/*.md. A string name references an existing connection; a name with a nested command or url is an inline definition.

We provide a read-only audit script. Save it in a trusted location and inspect its source before running it. Do not substitute a script of the same name from the cloned repository.

node /trusted-tools/agent-inline-mcp-audit.mjs /path/to/cloned-repo

It prints names, types, commands, args and URLs as JSON. It does not execute commands, connect to URLs, write settings or read .claude.json. Output args and URLs may contain secrets; do not publish them unreviewed.

This is a limited parser, not a complete YAML validator. It accepts two-space mappings and lists, simple scalars and JSON-formatted arrays. Unsupported syntax such as anchors or multiline values fails visibly. It rejects symlink agent files and target directories and files larger than 65,536 bytes. An error is not an empty result: inspect the text manually. User agents, plugins, recursive directories and other execution paths are outside its scope.

#Which debug log lines help?

In a log from an existing session, look for Skipping frontmatter MCP servers and not trusted. Our log named the isolated .claude.json and projects["<path>"].hasTrustDialogAccepted. Starting a new session to collect logs can run other MCP servers or hooks, so distinguish it from file-only inspection. Logs may also contain secrets.

#How can I stop startup?

These observations use trust of the definition folder. “No” means the dummy did not start; it does not certify safety of the whole session.

--strict-mcp-config excludes configuration other than --mcp-config, with an official exception for explicit --agents. Inspect servers you pass with --mcp-config too. Where managed-mcp.json is deployed, the documentation says strict causes startup to exit.

The --bare and --setting-sources user rows are observations on this version. Project and additional-directory agents also produced agent-not-found warnings, so these do not show an agent running with only its MCP disabled.

deniedMcpServers is described in the official policy documentation. In isolated user settings, [{"serverName":"dummy"}] stopped the dummy from every source. Rename resistance and organization-managed settings were not tested. disabledMcpjsonServers targets .mcp.json; do not assume it suppresses agent inline definitions.

#What did the 75-condition experiment find?

We enumerated five sources × three trust states × five suppressors. All 51 conditions with expectations fixed before execution matched. We left 24 combinations whose expectations were not determined from the documents as observations. The dummy started in 23 conditions. This is not a product performance or security score.

All runs used an unauthenticated environment and exited 1; some stopped because the selected agent was not found. In the 23 conditions that started the dummy, connections preceded the authentication error, so spawn, initialize and tools/list could be recorded without a model call. This does not establish response quality or connection success with a real service.

#How can the experiment be reproduced?

The expectations and observations for all 75 conditions are saved. Verification code and original-source SHA-256 hashes are also stored in repository records. The runner uses this Mac’s fixed paths; it is not a portable tool to execute unchanged elsewhere.

Every experiment used env -i and redirected HOME, CLAUDE_CONFIG_DIR, CODEX_HOME, TMPDIR, XDG_CONFIG_HOME and Git configuration into scratch. macOS sandbox-exec denied reads and writes to real configuration directories and outbound IP connections. The dummy was a local Node.js script; no external package was retrieved.

Instead of probing real settings, we applied the same deny rule to synthetic canaries and observed read/write failures. Removing the rule made both operations succeed. The comparator detected three mutations that erased trust, strict or source distinctions; an observer reading an empty marker failed the positive-control check. Real configuration values and hashes were not recorded.

#What remains untested?

We replaced interactive trust-dialog acceptance with a key in isolated JSON. Agent-tool subagent dispatch, the SDK, remote MCP, managed settings, plugins, Windows/Linux, older versions and authenticated real services were not measured. Reading a definition does not establish the safety of the command it names.

#Where are related guides and primary sources?

• MCP scopes and approval
• Read settings added by Postman
• Writes outside the working directory
• Skills and agent roles
• Claude Code instruction discovery
• AGENTS.md in Downloads
• Official CLI flags, configuration environment variables, MCP settings, settings reference

Check the definition source and launch flags as well as trust. For a repository you are not ready to execute, start by reading frontmatter.

#Frequently asked questions?

#Does a cloned repo’s subagent MCP start automatically?

Inline MCP in a project agent file waits for trust of its definition folder. After trust, it connects when the subagent starts, or at startup when selected as the main session with --agent. Cached remote connections have a lazy-connection exception.

#Does claude -p bypass this trust check?

No. Trusting only a parent folder is also insufficient for this inline MCP check. However, -p connects .mcp.json servers without asking for approval, so distinguish the two sources.

#Where is folder trust recorded?

The documentation names projects["<path>"].hasTrustDialogAccepted in ~/.claude.json. This experiment redirected storage under CLAUDE_CONFIG_DIR. Inspect what will run before manually granting trust.

#Does --strict-mcp-config also stop inline --agents servers?

No. The documentation exempts explicit caller input, and our 2.1.319 run started it. It also started under --bare, so inspect the definitions you pass.

#Is mcpServers in a plugin subagent used?

The documentation says mcpServers in plugin-provided subagents is ignored. We did not test a plugin in this run. Distinguish the definition source from a regular project agent.

#What about versions before v2.1.238?

The documentation says those versions loaded these servers without checking folder trust. Update and then verify configuration and behavior. We did not test an older binary.