Skip to content
BENIBIX Learn

.mcp.json vs ~/.claude.json

People think every MCP server lives in .mcp.json. Only the team's do. A server you add for yourself, in one project or in all of them, is saved in ~/.claude.json in your home folder. So .mcp.json goes into git and every teammate sees it, while ~/.claude.json never leaves your machine.

AI⌨️ Claude Code

.mcp.json

A file in a project that lists MCP servers the team shares.

.mcp.json is a file in a project's root that lists MCP servers for the whole team. It is what claude mcp add writes when you use --scope project, and it is meant to be committed. Before using a server from it, Claude Code asks each person to approve it. Servers you add for yourself go in ~/.claude.json instead.

Example
Emma adds the team's issue tracker server with --scope project. The .mcp.json goes into git, and each teammate approves it once.
Why it matters
It gives the whole team the same tools without each person adding them.
Full entry
AI⌨️ Claude Code

~/.claude.json

A file Claude Code writes for itself. It holds your account and MCP servers.

~/.claude.json is a file in your home folder that Claude Code writes for itself. It holds your account details and the MCP servers you added for yourself. It also holds state, such as which folders you trust, and global config keys that /config sets. It sits next to the ~/.claude folder, not inside it. If it breaks, Claude Code saves a copy in ~/.claude/backups.

Example
Emma added a server with claude mcp add, then looked for it in settings.json. It was in ~/.claude.json, where her own servers live.
Why it matters
It explains where your MCP servers and trust choices are kept.
Full entry

In one line

.mcp.json
A file in a project that lists MCP servers the team shares.
~/.claude.json
A file Claude Code writes for itself. It holds your account and MCP servers.