Claude Code keeps asking to edit .mcp.json or settings: what the prompt means

A permission prompt for .mcp.json or .claude/settings.json can come from different checks. First separate the file edit from project trust and MCP-server approval. Check the matching rule, its source, and the session’s permission mode before changing policy. Anthropic’s rolling documentation and issue #21221 were checked November 3, 2026.

Is Claude asking to edit a file or to use an MCP server?

Read the prompt title and action. An Edit or Write prompt concerns changing a file. An MCP approval prompt concerns connecting to or calling a server. Accepting one does not automatically approve the other: a session may need permission to edit .mcp.json, then separately ask whether to use the project-scoped server described in it.

Record the exact path, tool name shown in the prompt, working directory, Claude Code version, permission mode, and whether this is a trusted workspace. Redact private repository names and credentials from any notes shared publicly.

Why can a project allow rule still leave an edit prompt?

Check the mode first. Anthropic documents that the default Manual mode prompts for file modifications. Its acceptEdits mode accepts edits and common filesystem commands within the working directory or additional directories; that changes the session’s approval behavior and should be chosen deliberately. A one-time “Yes” or session-only approval is not the same as a durable rule.

Then inspect the rules in /permissions. File path rules use Edit(path) and Read(path); a path rule written as Write(path) does not match file edits. A matching ask rule takes precedence over allow, while a deny rule takes precedence over both. Project allow rules do not take effect until you accept the workspace trust dialog, so an untrusted folder can still prompt.

Why might .claude/settings.json need special attention?

This is Claude Code’s own project configuration. An approval prompt for changing it does not by itself establish that the permission system ignored a valid rule. Current documentation describes file modifications as approval-gated in Manual mode and says file-edit approvals can last only until the session ends. Settings keys also have scopes: a shared project file cannot set every user, managed, or global option. After a settings change, use /status to see which settings sources loaded, then /permissions to inspect the active permission rules and their source files.

Keep shared settings strict JSON: comments and trailing commas are invalid. Review the diff before sharing a change, especially if it changes permissions, hooks, environment values, or plugins. Do not move a personal credential or local override into a committed file.

Why does .mcp.json have another approval step?

A project-scoped server in .mcp.json is executable integration configuration. In interactive sessions, Claude Code documents a separate approval before using project-scoped servers. The server can remain pending until you review it. Project server approvals in checked-in settings do not apply until the workspace is trusted; a cloned repository cannot approve its own servers while untrusted.

Use claude mcp list or claude mcp get <name> to inspect server status, then review the exact command, arguments, URL, and environment references in the configuration before approving it. For an expected server, review the project and then accept the workspace trust dialog yourself. If you do not trust the repository or server, leave it unapproved. Do not suppress prompts by enabling every project server or switching to a broad bypass mode.

What should I check when the rule appears not to match?

1. Confirm you launched Claude Code in the repository and note the path Claude displays. A relative path rule may be evaluated from a different directory than you expected.
2. Open /permissions and confirm whether the rule is present, which settings file supplied it, and whether an ask or deny rule also matches. Verify that a file rule uses Edit(...), not Write(...).
3. If the rule comes from shared project settings, check whether the workspace trust dialog was accepted. Use /status to confirm which settings files loaded and look for a settings error.
4. For an MCP server, separately check its status and project approval. A file-edit rule does not approve the server, and server approval does not grant permission to edit the JSON file.
5. Make one narrow change, repeat the same safe action, and inspect the resulting diff. If it still differs from current docs, capture the version and a minimal reproduction without secrets; do not broaden permissions as a diagnostic shortcut.

What does Claude Code issue #21221 establish?

The January 27, 2026 issue reports that Claude Code 2.1.20 on macOS prompted to edit a nested .mcp.json and .claude/settings.json despite a project rule the reporter expected to allow the edits. The issue was closed as a duplicate of #17213; the bot also listed reports about recursive path matching, settings-file path matching, and MCP loading. That closure does not show that the particular symptom was fixed, nor that it reproduces in current releases. Treat it as one historical symptom report, not a current product rule.

Related Claude Code setup guides

For rule scopes, see the Claude Code permission decision guide. For MCP configuration locations, see the CLI and Desktop configuration map; for connection prompts, see the MCP approval troubleshooting guide.

Sources and scope

• Anthropic Configure permissions documents modes, rule precedence, path-rule syntax, and file-edit approval behavior.
• Anthropic Settings files and precedence documents settings scope, strict JSON, workspace trust, and checks with /status.
• Anthropic MCP documentation documents project-server approval, pending status, and workspace trust.
• Claude Code issue #21221 is a closed duplicate report from version 2.1.20 on macOS, included only as a historical symptom.

This guide follows rolling official documentation checked November 3, 2026. It does not test current Claude Code builds or establish the cause or resolution of the issue report.