[BUG] Confusing UX and silent failures for claude mcp add on Windows

[0x46y]

Preflight Checklist

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

What's Wrong?

The claude mcp add command on Windows is confusing and fails silently in some cases.

1. It incorrectly rejects valid arguments for subcommands (like uvx --from ...) with an error: unknown option.
2. When a workaround is used (a wrapper script), the command without a --scope flag reports that it successfully modified .claude.json, but it silently fails and doesn't actually write anything to the file.
3. The correct working method (--scope project) creates a new, unexpected .mcp.json file in the project directory, a behavior which is not clearly documented.

This combination of issues makes setting up an MCP server extremely difficult and frustrating for users on Windows.

What Should Happen?

1. The command should correctly parse arguments and pass them to the subcommand without throwing unknown option errors.
2. If the command fails to write to a configuration file, it should report an error, not a false success message.
3. The documentation and/or help text should clearly explain that project-level configuration creates a new .mcp.json file.

Error Messages/Logs

When trying to pass arguments directly:


error: unknown option '--from'


When running without `--scope` (this is a **false success message**):


Added stdio MCP server serena with command: run_serena.bat  to local config
File modified: C:\Users\YourUsername\.claude.json


*(Note: Despite this message, the file is not actually modified.)*

Steps to Reproduce

1. Create a wrapper script run_serena.bat to encapsulate a complex command like uvx --from git+https://github.com/oraios/serena serena-mcp-server ....
2. In a project directory on PowerShell, run claude mcp add serena run_serena.bat.
3. Observe the CLI outputs a success message claiming it modified ~/.claude.json.
4. Check the contents of ~/.claude.json and see that the mcpServers object is still empty ({}). This is the silent failure bug.
5. Now, run claude mcp add --scope project serena run_serena.bat.
6. Observe that this command correctly creates a new file named .mcp.json in the current project directory. This behavior is correct but unexpected and undocumented.

Claude Model

None

Is this a regression?

Unknown

Last Working Version

No response

Claude Code Version

1.0.115 (Claude Code)

Platform

Other

Operating System

Windows

Terminal/Shell

PowerShell

Additional Information

The confusing user experience led to a very long troubleshooting process. I have documented the final working solution in a Japanese tech blog post to help other users who might encounter the same problem: https://qiita.com/ysdog/items/c57088f728da4360fea7

However, fixing the CLI behavior and improving the documentation would be the ideal solution. Thank you

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] claude mcp add command fails when options are placed before required arguments #2341
2. [BUG] "Error: unknown option '-y'" when adding mcp with npx in native windows installation #3825
3. Docs: Discrepancy in claude mcp add scope storage locations #6888

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[0x46y]

Thank you for the additional context. I have reviewed all three linked issues, and it appears they each describe a piece of the overall problem I experienced.

1. Issues [BUG] claude mcp add command fails when options are placed before required arguments #2341 and [BUG] "Error: unknown option '-y'" when adding mcp with npx in native windows installation #3825 both correctly identify bugs in the argument parser, which was the first problem I encountered.
2. Issue Docs: Discrepancy in claude mcp add scope storage locations #6888 points out the documentation discrepancy regarding the .mcp.json storage location, which was the final piece of the puzzle for me.

However, none of these individual issues report the most critical bug in this chain: the silent failure. When the command is run without --scope project, it falsely claims to have successfully modified .claude.json when it has done nothing.

My report (#7672) is the only one that connects all these related problems into a single, cohesive user journey. It describes how the parser bug (#2341/#3825) leads to a workaround, which then triggers the silent failure bug, which is ultimately resolved by discovering the undocumented .mcp.json behavior (#6888).
Therefore, I believe this issue serves as a valuable comprehensive report on the end-to-end broken user experience for setting up MCPs on Windows. I recommend keeping it open as it provides the full context that the individual issues lack.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

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.