Skip to main content
What this unit solves~/.claude.json is Claude Code’s global state file. It stores MCP server registrations, per-project trust and tool-approval records, and a collection of onboarding and account metadata. It is not a policy file for you to hand-edit; the tool writes to it. But knowing what it stores lets you open the file and locate the root cause directly when MCP won’t load, permission dialogs keep firing, or trust state seems corrupted, rather than blindly reinstalling. This unit gives you a field-by-field tour, a verifiable MCP scope model, and a clear criterion for when hand-editing is acceptable and when it is not.

​
Learning objectives

  • Describe the broad categories of information stored in ~/.claude.json and identify the sections most useful for troubleshooting.
  • Distinguish the responsibility boundary between claude.json (state and registration) and settings.json (behavioral policy), and avoid mixing them up.
  • Explain MCP’s three scopes (local / project / user), where each is stored, and how .mcp.json project trust works.
  • Use the contents of claude.json to locate the root cause when an MCP server fails to load or a trust dialog fires repeatedly.

​
1. What claude.json is: a state file, not a policy file

~/.claude.json is a user-level state file located in your home directory (on Windows: C:\Users\<your-account>\.claude.json). Claude Code itself is the primary writer; if the file does not exist at first launch it is created automatically. It has a fundamental boundary with the settings.json discussed in 02-3:
FileThe question it answersWho writes itShould you hand-edit it
~/.claude.json”What has Claude Code remembered?” (which MCPs exist, does this project have trust, which tools have been approved)Written automatically by the toolNo (with narrow exceptions for troubleshooting; see Section 5)
settings.json”How should Claude Code behave?” (allow / deny policy, hooks, env)YouYes
settings.json describes “how to behave”: permission policy, hooks, env — the policy file you edit. claude.json records “what has happened”: which MCP servers were registered, which project you trusted, which tools you clicked “always allow” on. This is state maintained by the tool, not something you write. Keeping this boundary clear avoids the most common misuse: hand-writing “I always want to allow this tool” intent into claude.json rather than into settings.json’s permissions.allow. The former is state (written by the tool); the latter is policy (written by you). Mixing them means the tool’s next state update will overwrite whatever you wrote by hand.

​
2. What it stores: a field tour

The most important section of ~/.claude.json is projects: an object keyed by absolute project paths, with each project’s private state underneath, including the MCP servers registered at local scope for that project. The structure the official documentation provides (after you add a local server from /path/to/your/project) looks like this [1]: 
{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}
Beyond projects, the file stores a batch of tool-managed metadata: whether onboarding is complete, theme preference, launch count, login account information, and similar internal state.
Anthropic does not publish a complete claude.json schemaThe official documentation formally documents the MCP server structure at ~/.claude.json’s projects.<path>.mcpServers [1]. The remaining fields (theme, launch counter, account metadata, persisted tool approvals, etc.) are largely internal tool state; Anthropic has not published a complete schema (as of 2026-05). The descriptions of non-MCP fields in this section reflect what is commonly observed in practice, not a field-by-field official contract. This is exactly why you should not rely on hand-editing those fields: the format may change with tool updates.
When troubleshooting, the sections you will actually use are projects.<your-project-path>.mcpServers (first place to look when MCP won’t connect) and the project’s trust and tool-approval state (look here when the trust dialog keeps firing).

​
3. Division of labor with settings.json: memory vs. policy

Two practical rules: write policy into settings.json, not claude.json; let the tool maintain state, and do not reach around the tool to hand-edit trust records in claude.json.

​
4. MCP’s three scopes and .mcp.json trust

This is the section most worth clarifying when learning claude.json, because MCP configuration is spread across different locations and putting it in the wrong place produces a frustrating “I clearly added this but it’s invisible in my other project” experience. Claude Code’s MCP servers have three scopes (as of 2026-05) [1]:
ScopeLoaded byShared with teamStored in
local (default)Current project onlyNo~/.claude.json (under that project’s path)
projectCurrent project onlyYes (via version control).mcp.json (project root)
userAll your projectsNo~/.claude.json
When using claude mcp add, specify scope with --scope (options go before the server name, -- precedes the command) [1]: 
# local (default): current project only, private, stored in ~/.claude.json
claude mcp add --transport http stripe https://mcp.stripe.com

# project: team-shared, written to .mcp.json (committed to version control)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# user: available across all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
When the same server is defined in multiple places, Claude Code uses the highest-priority complete entry (fields are not merged across scopes): local > project > user > plugin-provided > claude.ai connector [1].
MCP’s “local scope” is not settings.local.jsonThis is a confusion point the official documentation explicitly calls out [1]: a local-scoped MCP server lives in ~/.claude.json (your home directory); the general local settings discussed in 02-3 live in .claude/settings.local.json (the project directory). Both have “local” in the name but serve entirely different purposes and live in entirely different places. One means “this MCP server is visible only in this project and only to me”; the other means “my personal settings override layer.”
.mcp.json project trust: the official documentation states explicitly that, for security, Claude Code requires you to approve a project-scoped server from .mcp.json before using it [1]. Servers awaiting approval show ⏸ Pending approval in claude mcp list; rejected servers show ✗ Rejected. To reset these approval choices, run claude mcp reset-project-choices.

​
5. Security boundaries and troubleshooting: when to touch it, when not to

Most of the time, leave claude.json alone. There are two categories of situations where hand-editing is reasonable, and two where it will break state. Safe to hand-edit: removing a stale MCP server entry (deleting one key from mcpServers); clearing an incorrect path trust record pointing to a project that has been moved. Do not hand-edit: bypassing the tool to directly change trust or approval records will put the file state out of sync with what the tool believes; editing an MCP server command without updating its env vars will cause the server to fail at startup while Claude Code still attempts to connect.
Back up before editingA damaged claude.json will disable all MCP and trust configuration. Back up first, then confirm the tool is working normally before removing the backup:
Copy-Item ~/.claude.json ~/.claude.json.bak
MCP troubleshooting order:
1

Check claude.json or .mcp.json

Look at ~/.claude.json’s projects.<current-project-path>.mcpServers (or .mcp.json) and verify the command path or URL for the server in question.
2

Verify env vars are complete

A stdio server missing an env key (API key or token) will fail to start.
3

Query status with tool commands

Use claude mcp list / claude mcp get <name> to inspect status, or use /mcp inside Claude Code to see connection state and tool count [1].
4

Check for Pending approval

A project-scoped server showing ⏸ Pending approval has not been approved yet — the connection is not broken.
Trust dialog firing repeatedly: usually means there is no matching path in projects, or the path does not match. On Windows, pay particular attention to path case, mixing backslashes and forward slashes, and trailing slash inconsistencies — any of these will be treated as a different project, triggering the trust request every time.
Supply chain risk: .mcp.json in an external repoWhen you clone an external repo it may include a .mcp.json defining MCP servers you do not recognize. Although project-scoped servers require your approval by default [1], if the enableAllProjectMcpServers auto-approve option is enabled, it effectively opens MCP execution to the external repo [2]. Checkpoint: after cloning an external repo and before trusting the directory, look at its .mcp.json and your ~/.claude.json to confirm no unrecognized servers have been added automatically. For the full threat model and related CVEs, see 03-3.

​
Tool comparison

The “tool-maintained state file” and “MCP scope layering” concepts vary considerably in maturity across tools (as of 2026-05; exact paths and keys are subject to each vendor’s current documentation):
ConceptAnthropic Claude (primary)OpenAI (Codex)Google (Gemini CLI)Cursor
Tool-maintained state file~/.claude.json (MCP registration, trust, tool approvals) [1]Needs source verificationNeeds source verificationNeeds source verification
MCP server config locationlocal / user stored in ~/.claude.json; project stored in .mcp.json [1]MCP section in config.toml (exact keys need source verification)mcpServers section in settings.json.cursor/mcp.json (needs source verification)
MCP scope layeringlocal / project / user, three layers [1]Needs source verificationNeeds source verificationNeeds source verification
Project MCP requires trust approvalYes, .mcp.json requires approval by default [1]Needs source verificationNeeds source verificationNeeds source verification
MCP is a cross-tool standard; scope models differMCP is an open standard and most agent tools support connecting to MCP servers. The differences lie in “where configuration is stored, whether there is scope layering, and whether project-level servers require forced approval.” Claude Code’s three-layer local / project / user model combined with mandatory .mcp.json approval is currently the most complete [1]; other tools typically have a single configuration location with weaker or less documented scope and trust models. Entries that cannot be confirmed are marked “needs source verification”; consult each vendor’s official documentation.

​
Hands-on exercises

1

Read ~/.claude.json and identify the three key sections

Open the file, locate projects.<one-of-your-project-paths>, and identify the mcpServers underneath (the local-scope servers). Cross-reference with claude mcp list output to confirm the file contents match what the tool believes.
2

Simulate an MCP connection failure and locate it

First back up with Copy-Item ~/.claude.json ~/.claude.json.bak. Deliberately corrupt the command path of a stdio server, launch Claude Code, and observe its status with /mcp (it should show a failure). Then work through the Section 5 troubleshooting sequence to locate and correct it. Delete the backup once everything is confirmed working.

​
Common pitfalls

Anti-pattern list
  • Hand-writing “always allow” into claude.json: to batch-approve tools in advance, edit settings.json’s permissions.allow (policy). Hand-editing the approval records in claude.json (state) will be overwritten when the tool next updates state.
  • Reinstalling the tool when MCP won’t connect: look first at whether the command path and env vars for the server entry in claude.json / .mcp.json are correct. Most problems are there, not in the tool itself.
  • Clicking “allow for this session only” then complaining that every session asks again: that option is intentionally non-persistent. To make it stick, choose the persistent option and let the tool write the state.
  • Treating MCP’s local scope as the same as settings.local.json: they occupy different locations and serve different purposes (see the Section 4 callout). Store it in the wrong place and the server will not be found.
  • Editing claude.json without a backup: a corrupted file disables all MCP and trust configuration.

​
Self-check

The bar for passing this unit
  1. Can you state in one sentence what distinguishes claude.json (state, written by the tool) from settings.json (policy, written by you)? If you want to batch-allow a tool, which file do you edit?
  2. You want an MCP server visible only in a specific project and not shared with the team. Which scope do you use and which file does it live in? What about sharing with the team?
  3. MCP local scope is stored in ~/.claude.json. What is .claude/settings.local.json? How are the two different?
  4. The trust dialog keeps firing in the same project. Which section of claude.json do you check first? What is the most likely cause on Windows?
  5. You clone an external repo that ships a .mcp.json. By default, will its servers connect immediately? What setting would cause them to be auto-approved?

​
Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.
  • [1] Anthropic, “Connect Claude Code to tools via MCP,” Claude Code Docs. (MCP three scopes local / project / user and storage locations; ~/.claude.json’s projects.<path>.mcpServers structure; .mcp.json project-scoped server requires approval, claude mcp reset-project-choices, ⏸ Pending approval; claude mcp add --scope; MCP local scope is distinct from settings.local.json; scope priority order) https://code.claude.com/docs/en/mcp (as of 2026-05)
  • [2] Anthropic, “Claude Code settings,” Claude Code Docs. (enableAllProjectMcpServers auto-approves project MCP; enabledMcpjsonServers / disabledMcpjsonServers; managed-layer allowedMcpServers / deniedMcpServers) https://code.claude.com/docs/en/settings (as of 2026-05)
  • Related: 02-3 on the policy side of settings.json and local settings; 02-5 on plugin-provided MCP servers; 01-6 on where permissions and trust sit within the harness; 03-3 on the supply chain threat model for external repos and MCP; 04-9 for in-depth MCP integration configuration.