[DOCS] `disabledMcpServers` and `enabledMcpServers` settings docs do not explain the non-array crash fixed in v2.1.200

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

The settings reference rows for disabledMcpServers (managed settings), enabledMcpServers, and the related mcpServers/disabledMcpjsonServers rows, plus the MCP configuration troubleshooting guidance.

Current Documentation

The enabledMcpServers row in settings.md describes the value as an allowlist without mentioning its required shape:

List of specific MCP servers from ~/.claude.json to approve. As of v2.1.196, claude mcp list and claude mcp get honor this key in an untrusted folder only from settings files that aren't checked into the repository

The disabledMcpServers row in the managed settings table in settings.md describes a denylist with the same shape:

An individual invalid entry is stripped and the valid subset is enforced. A wholly invalid value is dropped with a warning, since denying every server would block servers the policy never named.

The MCP reference at https://code.claude.com/docs/en/mcp describes valid configuration shapes for mcpServers blocks but does not describe the type contract for the allow/deny lists in .claude.json.

What's Wrong or Missing?

A. The shape contract for disabledMcpServers/enabledMcpServers is not stated

The v2.1.200 changelog says:

Fixed a crash at startup when disabledMcpServers or enabledMcpServers in .claude.json is set to a non-array value

Before v2.1.200, setting either key to a non-array value (for example a string, an object, or null) crashed Claude Code at startup. After v2.1.200 the value is tolerated, but the settings reference for both keys never states that the value must be an array of server names. Users editing .claude.json by hand have no docs entry to point them at the expected shape.

B. The crash is not mentioned in troubleshooting

Before v2.1.200 the only way to recover from a hand-edited .claude.json that set either key to a non-array was to delete or correct the value. There is no troubleshooting entry that says "if Claude Code crashes immediately after you edited .claude.json, check disabledMcpServers and enabledMcpServers are arrays". The fix exists; the diagnosis hint does not.

C. The "invalid entry is stripped" wording in settings.md only covers array elements

The disabledMcpServers managed-settings row says "an individual invalid entry is stripped and the valid subset is enforced", but that wording assumes the outer value is already an array. It does not address the case where the entire value is the wrong shape, which is exactly the case v2.1.200 had to defend against.

Suggested Improvement

Option A: Add the array contract to the two settings rows

Update settings.md so both rows explicitly state the required shape, for example:

disabledMcpServers — An array of MCP server names from ~/.claude.json to disable. Must be a JSON array; a string, object, null, or missing value is treated as an unset list and no servers are denied. Set in managed settings. Example: ["filesystem", "github"].

Mirror the same wording for enabledMcpServers, noting that a non-array value is treated as an unset list and no servers are auto-approved.

Option B: Add a troubleshooting entry

Add to https://code.claude.com/docs/en/troubleshooting (or whichever page covers ~/.claude.json validation) a note:

Claude Code crashes immediately on startup after editing ~/.claude.json: check that disabledMcpServers and enabledMcpServers are JSON arrays of strings. Other shapes were a hard crash before v2.1.200 and are silently ignored after, so a typo can disable or enable more servers than you intended.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/settings | ~207-234 | disabledMcpServers row in the managed settings table |
| https://code.claude.com/docs/en/settings | ~209 | allowManagedMcpServersOnly row mentions the same allowlist path |
| https://code.claude.com/docs/en/mcp | 297-330 | MCP scope section describes ~/.claude.json storage but not the shape contract |

Total scope: 2 pages that should state the required array shape for the two settings; 1 page that should add a troubleshooting entry for the pre-v2.1.200 crash.

The release note for this fix appears in v2.1.200 (July 3, 2026).