--mcp-config
A Claude Code CLI flag, read out of the shipped bundle. It has been in the build since v2.1.138, including the newest one read.
Load MCP servers from JSON files or strings (space-separated). When you pass this flag with -p, Claude Code waits for still-pending servers to connect before running the first turn, up to the MCP_TIMEOUT startup timeout, 30 seconds by default; a server with a cached tool list skips the wait and connects on first use. The wait requires Claude Code v2.1.221 or later
Anthropic's own wording. Read off CLI reference, captured 2026-09-26.
In the changelogs
32Releases whose published page names --mcp-config.
-
v2.1.305
Startup warnings for MCP servers now go to stderr only in non-interactive runs
Warnings about invalid or blocked MCP servers now print to stderr in non-interactive runs and go to the log otherwise
found in this entry's text
-
v2.1.301
MCP servers loaded with --mcp-config now receive connection options
A set of connection options is now passed through to MCP servers loaded with --mcp-config, for both required and normal servers
found in this entry's text, named in this entry
-
v2.1.301
Servers from --mcp-config can be kept despite the allowlist, with a notice
Some servers passed with
--mcp-configcan now be kept even if an allowlist would drop them, and Claude Code records a notice when it doesfound in this entry's text, named in this entry
-
v2.1.300
Update restart is refused if a launch settings file is gone
Claude Code will not restart a session onto a new version if a file passed with --settings or --mcp-config can no longer be read
found in this entry's text, named in this entry
-
v2.1.299
Remote runners can receive MCP servers from a file named by an environment variable
In remote sessions,
CLAUDE_CODE_REMOTE_MCP_CONFIGpoints the runner to a file of MCP servers delivered by the hostfound in this entry's text, named in this entry
-
v2.1.299
Some MCP servers from
--mcp-configcan now be refused, with a warningServers from several
--mcp-configsources now pass a check that can refuse some, and a failed Remote Control tool call says not to retryfound in this entry's text, named in this entry
-
v2.1.295
Agent SDK passes options so values starting with a dash are not misread
The Agent SDK now passes many options as
--flag=value, so a value starting with a dash is no longer mistaken for another flagfound in this entry's text, named in this entry
-
v2.1.292
Keep an MCP server's tool calls from moving to the background
A new
disableAutoBackgroundMCP server option stops Claude Code from moving that server's tool calls to the background on its ownfound in this entry's text
-
v2.1.292
MCP servers can stay out of automatic backgrounding with
disableAutoBackgroundA new per-server
disableAutoBackgroundfield stops Claude Code from moving that MCP server's tool calls to the backgroundfound in this entry's text
-
v2.1.290
disableClaudeAiMcpnow also blocks claude.ai servers you add yourselfWith
disableClaudeAiMcpset, a claude.ai proxy server passed by--mcp-configor the SDKmcpServersoption no longer connects eitherfound in this entry's text, named in this entry
-
v2.1.286
Remote worker sessions can wait for specific MCP servers before the first turn
CLAUDE_CODE_MCP_PREWAIT_SERVERSandCLAUDE_CODE_MCP_PREWAIT_SERVERS_MSname MCP servers for remote worker sessions to wait for before the first turnfound in this entry's text
-
v2.1.286
Change to how servers from
--mcp-configare connectedConnecting MCP servers loaded with
--mcp-confignow accepts two new internal options that can skip the step for servers not marked requiredfound in this entry's text, named in this entry
-
v2.1.285
Claude in Chrome can come from the remote session host instead of the built-in server
If the remote host supplies Claude in Chrome through
--mcp-config, Claude Code uses that and does not start its own Chrome serverfound in this entry's text
-
v2.1.281
Hidden --managed-settings flag added to
claude agentsand forwarded to dispatched sessionsclaude agentsgains a hidden--managed-settings <json>option that is passed on to sessions it startsfound in this entry's text
-
v2.1.281
Teammate spawn commands carry --managed-settings, --mcp-config and --strict-mcp-config
Spawned teammates and agents now inherit --managed-settings, --mcp-config and --strict-mcp-config from the launching command
found in this entry's text, named in this entry
-
v2.1.281
--tmux worktree relaunch absolutizes path arguments
When --tmux relaunches Claude Code for a worktree, relative file paths in flags are now turned into full paths
found in this entry's text
-
v2.1.281
bg dispatch carries reattachEnv and retries while the daemon starts
Background dispatch now retries while the daemon starts, carries a reattach environment, and forwards flags like
--settingswhen attachingfound in this entry's text
-
v2.1.242
Cloud-hosted sessions now refuse local CLI options instead of quietly dropping them
Running with --cloud now tells you which local CLI options were ignored or refused, and why.
found in this entry's text
-
v2.1.239
Command-line flag parsing rewritten around an explicit table of value-taking flags
Flags that take values no longer swallow or drop their arguments, and
--is handled.named in this entry, found in this entry's text
-
v2.1.239
Administrators can forbid server-delivered MCP servers with
disableSideloadFlagsAdmins can set disableSideloadFlags to block --mcp-config and refuse MCP servers pushed in from outside your config.
named in this entry, found in this entry's text
-
v2.1.239
Remote Control bridge sessions reject foreign --mcp-config entries
Remote Control bridge children reject foreign --mcp-config servers and rebuild the meta server themselves.
named in this entry, found in this entry's text
-
v2.1.239
Remote sessions drop disallowed --mcp-config servers instead of failing the run
Remote sessions drop disallowed --mcp-config servers and keep running instead of failing.
named in this entry, found in this entry's text
-
v2.1.239
More specific explanations when an --mcp-config is ignored
Skipped --mcp-config servers now name managed settings or a Remote Control child as the reason.
named in this entry, found in this entry's text
-
v2.1.229
Enterprise managed-mcp.json takes exclusive control of MCP servers
In remote mode an enterprise MCP config drops all other MCP servers, explaining each one.
named in this entry, found in this entry's text
-
v2.1.229
Enterprise MCP config now overrides
--mcp-configwith a named warningWhen enterprise MCP config wins over your
--mcp-config, the log names the file and dropped servers.named in this entry, found in this entry's text
-
v2.1.219
MCP servers skipped by --mcp-config are now reported
MCP servers rejected from --mcp-config are now listed on stderr and in the init message instead of vanishing.
named in this entry, found in this entry's text
-
v2.1.193
disableSideloadFlagsEnterprise Settingfound in this entry's text
-
v2.1.182
disableClaudeAiConnectorsSettingfound in this entry's text
-
v2.1.163
Hermetic Mode MCP Config Filtering
found in this entry's text
-
v2.1.122
MCP Server Duplicate Detection UI
found in this entry's text
- v2.1.89
- v2.1.64
First cited
6The earliest release whose published evidence quoted --mcp-config was v2.1.219, 24 Jul 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
Presence across releases
1Build by build
149One row per release since the first build this name was read out of. Absent means the build was read and the name was not in it, never mined means no bundle for that release was ever archived, and a declared type or a default is only ever what that release's own bundle stated.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.