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

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 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