{"name":"--mcp-config","slug":"mcp-config","family":"cli","title":"CLI flags","noun":"CLI flag","description":"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`](\/docs\/en\/env-vars) startup timeout, 30 seconds by default; a server with a [cached tool list](\/docs\/en\/mcp#managing-your-servers) skips the wait and connects on first use. The wait requires Claude Code v2.1.221 or later","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":"2.1.138","removed_in":null,"in_current_build":true,"newest_mined":"2.1.308","builds":149,"mined_builds":149,"first_cited":{"version":"2.1.219","released_at":"2026-07-24 16:11:49","spans":6}},"aliases":[],"entries":[{"version":"2.1.305","anchor":"warnings-from-print-mode-startup-go-through-a-new-helper-and","heading":"Startup warnings for MCP servers now go to stderr only in non-interactive runs","line":"Warnings about invalid or blocked MCP servers now print to stderr in non-interactive runs and go to the log otherwise","released_at":"2026-10-20 19:29:36","reason":"found in this entry's text"},{"version":"2.1.301","anchor":"mcp-dialoptions-threaded-through-connection","heading":"MCP servers loaded with --mcp-config now receive connection options","line":"A set of connection options is now passed through to MCP servers loaded with --mcp-config, for both required and normal servers","released_at":"2026-10-15 14:34:23","reason":"found in this entry's text, named in this entry"},{"version":"2.1.301","anchor":"mcp-config-allowlist-exempt-servers-and-notes","heading":"Servers from --mcp-config can be kept despite the allowlist, with a notice","line":"Some servers passed with `--mcp-config` can now be kept even if an allowlist would drop them, and Claude Code records a notice when it does","released_at":"2026-10-15 14:34:23","reason":"found in this entry's text, named in this entry"},{"version":"2.1.300","anchor":"update-restart-refused-when-launch-settings-mcp-config-f","heading":"Update restart is refused if a launch settings file is gone","line":"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","released_at":"2026-10-14 14:27:26","reason":"found in this entry's text, named in this entry"},{"version":"2.1.299","anchor":"claude-code-remote-mcp-config-runner-receives-delivered-mcp","heading":"Remote runners can receive MCP servers from a file named by an environment variable","line":"In remote sessions, `CLAUDE_CODE_REMOTE_MCP_CONFIG` points the runner to a file of MCP servers delivered by the host","released_at":"2026-10-14 00:23:19","reason":"found in this entry's text, named in this entry"},{"version":"2.1.299","anchor":"mcp-mcp-config-handling-and-remote-control-remote-tool-cal","heading":"Some MCP servers from --mcp-config can now be refused, with a warning","line":"Servers from several `--mcp-config` sources now pass a check that can refuse some, and a failed Remote Control tool call says not to retry","released_at":"2026-10-14 00:23:19","reason":"found in this entry's text, named in this entry"},{"version":"2.1.295","anchor":"sdk-spawns-cli-with-flagvalue-form-and-guards-values-st","heading":"Agent SDK passes options so values starting with a dash are not misread","line":"The Agent SDK now passes many options as `--flag=value`, so a value starting with a dash is no longer mistaken for another flag","released_at":"2026-10-08 18:22:58","reason":"found in this entry's text, named in this entry"},{"version":"2.1.292","anchor":"mcp-servers-get-a-disableautobackground-option-new-config-k","heading":"Keep an MCP server's tool calls from moving to the background","line":"A new `disableAutoBackground` MCP server option stops Claude Code from moving that server's tool calls to the background on its own","released_at":"2026-10-06 17:10:31","reason":"found in this entry's text"},{"version":"2.1.292","anchor":"mcp-servers-can-opt-out-of-auto-backgrounding","heading":"MCP servers can stay out of automatic backgrounding with disableAutoBackground","line":"A new per-server `disableAutoBackground` field stops Claude Code from moving that MCP server's tool calls to the background","released_at":"2026-10-06 17:10:31","reason":"found in this entry's text"},{"version":"2.1.290","anchor":"disableclaudeaimcp-setting-explicit-claudeai-proxy-servers","heading":"disableClaudeAiMcp now also blocks claude.ai servers you add yourself","line":"With `disableClaudeAiMcp` set, a claude.ai proxy server passed by `--mcp-config` or the SDK `mcpServers` option no longer connects either","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text, named in this entry"}],"entries_total":32,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"claude-code","path":"agent-view","title":"Manage multiple agents with agent view","documented":false},{"source":"claude-code","path":"changelog","title":"Claude Code changelog","documented":false},{"source":"claude-code","path":"github-actions","title":"Claude Code GitHub Actions","documented":false},{"source":"claude-code","path":"headless","title":"Run Claude Code programmatically","documented":false},{"source":"claude-code","path":"managed-mcp","title":"Control MCP server access for your organization","documented":false},{"source":"claude-code","path":"managed-settings","title":"Deploy managed settings","documented":false},{"source":"claude-code","path":"mcp","title":"Connect Claude Code to tools via MCP","documented":false},{"source":"claude-code","path":"plugins\/mods\/admin","title":"Manage mods for your organization","documented":false},{"source":"claude-code","path":"plugins\/org","title":"Manage Claude Code plugins for your organization","documented":false}],"docs_total":13,"gates":[],"related":[{"name":"--mcp-debug","slug":"mcp-debug","description":null}],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/mcp-config","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}