[BUG] Claude CLI Ignores `--mcp-config` and `--strict-mcp-config` Flags

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

The --mcp-config and --strict-mcp-config command-line flags are completely ignored by Claude Code CLI commands. All commands always use the default configuration file (~/.mcp.json) regardless of which config file is explicitly specified.

This bug can be clearly demonstrated with claude mcp list, but it affects all Claude CLI commands including:

• claude mcp list - Cannot verify which config will be used
• claude <prompt> - Cannot use custom MCP configs in interactive sessions
• Any automation using --mcp-config for dynamic configuration

When running:

claude --mcp-config /path/to/custom-config.json --strict-mcp-config mcp list

The command shows servers from ~/.mcp.json instead of the specified config file.

This occurs with:

• Empty config files (should show "No MCP servers configured")
• Config files with different servers (should show only those servers)
• Any custom config path provided via --mcp-config

All test cases return identical output showing the default configuration, proving the flags are completely ignored across all commands.

What Should Happen?

When using claude --mcp-config <file> --strict-mcp-config <command>, ALL Claude CLI commands should:

1. Load configuration ONLY from the specified file (not from ~/.mcp.json)
2. Use servers defined in that file (and only those servers)
3. Respect the --strict-mcp-config flag by ignoring all other config sources

For example:

• Empty config: Commands should have no MCP servers available
• Custom config with different servers: Commands should use only those servers, not default ones
• Per-project configs: Each project can have its own MCP server configuration

This is critical for:

• CI/CD pipelines - Testing different configurations per job/environment
• Docker containers - Container-specific configs that differ from host
• Multi-project workflows - Different MCP servers per project (dev tools vs production tools)
• Environment isolation - Development, staging, production configs
• Automation scripts - Dynamic MCP configuration based on context
• mcp-coder workflows - Per-repository MCP server definitions

Error Messages/Logs

No error messages are displayed. The command runs successfully but shows incorrect output.

**Test 2 - Actual output** (empty config should show nothing):

Checking MCP server health...

podman: npx -y podman-mcp-server@latest - ✓ Connected


**Test 2 - Expected output**:

No MCP servers configured. Use `claude mcp add` to add a server.


**Test 3 - Actual output** (should show filesystem, not podman):

Checking MCP server health...

podman: npx -y podman-mcp-server@latest - ✓ Connected


**Test 3 - Expected output**:

Checking MCP server health...

filesystem: npx -y @modelcontextprotocol/server-filesystem@latest /tmp - ✓ Connected

Steps to Reproduce

Setup: Create a simple default configuration

Create ~/.mcp.json with one server:

{
  "mcpServers": {
    "podman": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "podman-mcp-server@latest"],
      "autoApprove": ["*"]
    }
  }
}

Test 1: Baseline - Default configuration

claude mcp list

Expected output:

Checking MCP server health...
podman: npx -y podman-mcp-server@latest - ✓ Connected

Actual output: ✓ Shows podman server (correct)

Test 2: Empty config with flags (THE BUG)

Create empty config file:

{"mcpServers":{}}

Run:

claude --mcp-config empty-config.json --strict-mcp-config mcp list

Expected output:

No MCP servers configured. Use `claude mcp add` to add a server.

Actual output: ❌

Checking MCP server health...
podman: npx -y podman-mcp-server@latest - ✓ Connected

Shows podman from default config - flags are IGNORED!

Test 3: Custom config with different server (THE BUG)

Create custom config with a different server:

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem@latest", "/tmp"]
    }
  }
}

Run:

claude --mcp-config custom-config.json --strict-mcp-config mcp list

Expected output:

Checking MCP server health...
filesystem: npx -y @modelcontextprotocol/server-filesystem@latest /tmp - ✓ Connected

Actual output: ❌

Checking MCP server health...
podman: npx -y podman-mcp-server@latest - ✓ Connected

Shows podman from default config - should show filesystem!

Automated reproduction script

Complete test script that demonstrates this bug:

echo Creating default config with podman server...
echo {"mcpServers":{"podman":{"type":"stdio","command":"npx","args":["-y","podman-mcp-server@latest"]}}} > .mcp.json

echo.
echo TEST 1: Default config
claude.exe mcp list

echo.
echo TEST 2: Empty config with --mcp-config --strict-mcp-config
echo {"mcpServers":{}} > empty.json
claude.exe --mcp-config empty.json --strict-mcp-config mcp list

echo.
echo TEST 3: Custom config with different server
echo {"mcpServers":{"filesystem":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem@latest","/tmp"]}}} > custom.json
claude.exe --mcp-config custom.json --strict-mcp-config mcp list

echo.
echo If all three tests show "podman" server, the bug exists!

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

N/A - Unknown if this ever worked correctly

Claude Code Version

2.0.31 (Claude Code)

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

Impact

This is a critical bug that breaks core CLI functionality. It affects:

Automation & CI/CD:

• Cannot use different MCP configs per pipeline job/stage
• Cannot verify MCP configuration before running automated workflows
• Cannot test different MCP server combinations
• Breaks all scripts that rely on --mcp-config for dynamic configuration

Containerization:

• Docker containers cannot use container-specific configs
• Always falls back to host's ~/.mcp.json (which may not exist in container)
• Breaks containerized mcp-coder workflows and other tools
• Cannot create reproducible containerized environments

Multi-Project/Multi-Environment:

• Cannot have per-project MCP server definitions
• Cannot isolate development/staging/production MCP configurations
• All projects forced to use the same global MCP servers
• Breaks workflows that need different tools per repository

Development & Testing:

• Cannot test MCP configurations before deploying
• Cannot reproduce issues with specific MCP server combinations
• Cannot switch between different MCP setups easily

The documented flags are completely non-functional, making features like --strict-mcp-config misleading documentation.

Related Issues

• #5593 - --mcp-config flag broken (argument parsing bug + schema validation)
• #5963 - Project-scope servers not displayed in claude mcp list
• #6855 - v1.0.98 ignores .mcp.json file

Workaround

None available for the mcp list command. Users must:

1. Manually read and parse config files
2. Skip configuration verification entirely
3. Hope runtime configuration matches expectations

Test Results Summary

All three tests show identical output (podman server), proving:

• --mcp-config flag is completely ignored
• --strict-mcp-config flag is completely ignored
• mcp list always reads from ~/.mcp.json regardless of flags

Scope of Bug

Demonstrated with mcp list: This bug report uses claude mcp list as a clear, easy-to-verify test case because it shows the exact config being used.

Likely affects all commands: Based on the test results showing mcp list completely ignoring the flags, it's highly probable that:

• claude <prompt> interactive sessions also ignore --mcp-config
• mcp-coder and other tools using --mcp-config are also affected
• All Claude CLI commands that accept these flags are broken

Why this matters: Without a working mcp list to verify configuration, users have no way to confirm if their --mcp-config will work for other commands. This makes the entire feature unusable for automation and testing.

Suggested Fix

All Claude CLI commands should respect --mcp-config and --strict-mcp-config flags by:

1. Loading configuration from specified file(s) only
2. Ignoring default config locations when --strict-mcp-config is set
3. Using servers from the loaded configuration for all operations

This would make the CLI behavior consistent with the documented behavior of these flags and enable the critical use cases they were designed for (per-project configs, containerization, CI/CD, etc.).