[BUG] --mcp-config freezes claude command with or without existing MCP config file

Interestingly enough, this has disappeared now. Maybe something on the Claude Code server-side? Closing as irrelevant.

this is happening for me on both 2.1.7 and 2.1.12 with kitty/zsh on both macos and nixos

Reopening, since it seems to be a non-local bug. It works for me now without any changes but it seems it happens to other users as well.

i also changed nothing and it worked once, and now seems to not be working again

very weird

I've started to randomly experience this again. In one terminal, everything worked fine, Claude Code started. 40 minutes later, another terminal, same environment, same credentials, same startup command line - and it's stuck.

OK, this is not random anymore. I found out that I had 2 different MCP configs in 2 different projects. The one that halted Claude's execution was using incorrect syntax (I think it was copied over from VibeKanban or some other place which has different MCP syntax than Claude Code). Still, Claude CLI should check this and not just freeze when this happens.

I think the same problem also happens when the mcp_settings.json file that I'm using does not exist at all. Instead of showing an error, Claude Code will just freeze.

+1. When I pass in a JSON string into --mcp-config that isn't the right syntax, it freezes

Additional confirmation: --mcp-config hangs when stdout is a pipe (non-TTY)

We encountered this exact issue in our .NET application (F#) that spawns Claude CLI as a child process with ProcessStartInfo:

let psi = ProcessStartInfo(
FileName = "claude",
UseShellExecute = false,
RedirectStandardOutput = true, // Creates pipe, not TTY
RedirectStandardError = true,
RedirectStandardInput = true,
CreateNoWindow = true
)
Behavior:

Without --mcp-config: Works fine ✅
With --mcp-config (any valid JSON): Process hangs indefinitely with 0% CPU ❌
Same MCP config works when run directly in terminal (TTY) ✅
Versions tested:

v2.1.7+: Hangs with --mcp-config when stdout is a pipe
v2.1.6: Works correctly - no hang
Workaround:
We pinned to v2.1.6:

curl -fsSL https://claude.ai/install.sh | bash -s 2.1.6
Additional note about --mcp-config being variadic:
When using v2.1.6, we also discovered that --mcp-config appears to be variadic (consumes all subsequent arguments). If you have other arguments after it, they get parsed as MCP config paths:

This fails - "myprompt" gets parsed as MCP config file

claude --mcp-config '{"mcpServers":{...}}' -p myprompt

This works - prompt comes BEFORE --mcp-config

claude -p myprompt --mcp-config '{"mcpServers":{...}}'
Environment:

macOS Darwin 25.2.0
.NET 10 / F#
ProcessStartInfo with redirected stdout/stderr/stdin

+1, Encountered the same bug.

Still seeing it though it seems to only happen the map config itself is invalid. Also, the process freezes entirely; that's a weird one. If I kill -9 it, I get a JOB failure message from fish.

<img width="729" height="42" alt="Image" src="https://github.com/user-attachments/assets/f0e2d9f7-c6bf-4675-abd9-ce1d1f06c500" />

Is Claude backgrounding itself?

Just faced the same problem where claude hangs on startup when using --mcp-config flag.

I found out that this happens when the "type": "http" is missing from a remote MCP server configuration defined in the file being passed via the --mcp-config argument.

How to reproduce ?

1. Write an incorrect.json mcp config file with the following content

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_MCP_SERVER_TOKEN}"
      }
    }
  }
}

1. Run claude with claude --mcp-config incorrect.json
2. claude does not start and no output is shown

How to fix

To fix this issue add the type: http field to the mcp server definition.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "type": "http",
      "headers": {
        "Authorization": "Bearer ${GITHUB_MCP_SERVER_TOKEN}"
      }
    }
  }
}

More informations

Here are the claude debug logs:

$ cat ~/.claude/debug/latest
2026-03-02T15:59:23.297Z [DEBUG] detectFileEncoding failed for expected reason: ENOENT
2026-03-02T15:59:23.298Z [DEBUG] MDM settings load completed in 1ms
2026-03-02T15:59:23.308Z [DEBUG] detectFileEncoding failed for expected reason: ENOENT
2026-03-02T15:59:23.308Z [DEBUG] detectFileEncoding failed for expected reason: ENOENT
2026-03-02T15:59:23.309Z [DEBUG] [init] configureGlobalMTLS starting
2026-03-02T15:59:23.309Z [DEBUG] [init] configureGlobalMTLS complete
2026-03-02T15:59:23.309Z [DEBUG] [init] configureGlobalAgents starting
2026-03-02T15:59:23.309Z [DEBUG] [init] configureGlobalAgents complete
2026-03-02T15:59:23.310Z [DEBUG] detectFileEncoding failed for expected reason: ENOENT
2026-03-02T15:59:23.316Z [DEBUG] Git remote URL: null
2026-03-02T15:59:23.316Z [DEBUG] No git remote URL found
2026-03-02T15:59:23.523Z [DEBUG] Remote settings: No settings found (404)
2026-03-02T15:59:23.529Z [DEBUG] Programmatic settings change notification for policySettings

My environment

$ claude --version
2.1.63 (Claude Code)
$ uname -a
Linux x1 6.6.122-1-MANJARO #1 SMP PREEMPT_DYNAMIC Sat Jan 31 00:26:06 UTC 2026 x86_64 GNU/Linux

edited: added how to fix

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

it's fixed for me in one of the newer Claude Code versions

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.