claude-code - 💡(How to fix) Fix [DOCS] `/doctor` MCP troubleshooting docs omit missing-field and source-file diagnostics added in v2.1.136

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/debug-your-config

Section/Topic

/doctor configuration diagnostics, especially the "Check resolved settings" and "Check MCP servers" guidance

Current Documentation

The docs currently say:

Run /doctor to validate your configuration files and surface invalid keys or schema errors. Run /status to see which settings sources are active, including whether managed settings are in effect. To understand which scope wins for a given key, see How scopes interact.

Run /mcp to see every configured server, its connection status, and whether you have approved it for the current project.

• A server that fails to start shows as failed in /mcp. Relative file paths in command or args are a frequent cause, since they resolve against the directory you launched Claude Code from rather than the location of .mcp.json.

What's Wrong or Missing?

As of v2.1.136, /doctor has improved MCP schema diagnostics: it names the missing field and shows which source file contains the invalid MCP entry. The current docs still describe /doctor only at a high level and do not tell users that MCP schema errors are now pinpointed this way.

That leaves a gap for .mcp.json troubleshooting. Users are told to run /doctor for schema errors and /mcp for server status, but they are not told that /doctor can now identify the exact missing field and the file path they need to fix.

Suggested Improvement

Update the /doctor troubleshooting guidance to explicitly mention MCP schema validation details added in v2.1.136.

For example, add a note near the existing /doctor guidance such as:

For invalid MCP configuration, /doctor now reports the missing field and the source file path for the failing entry, which helps distinguish whether the problem is in project .mcp.json, user config, or another scope.

It would also help to cross-reference this from the MCP page near the .mcp.json format and parsing guidance.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

This gap is about the MCP configuration debugging improvement shipped in v2.1.136.