Claude Code settings.json: Full Configuration Reference 2026
Claude Code reads settings from `.claude/settings.json` in your project (checked into git, shared with team) and `~/.claude/settings.json` for user-level overrides. The most important fields are `permissions` (what tools Claude can use without asking) and `mcpServers` (external tool integrations).
Claude Code has a two-tier settings system. Project settings live at `.claude/settings.json` in your repository root — commit this to share configuration with the whole team. User settings live at `~/.claude/settings.json` — these are personal overrides that apply to all your projects. User settings take precedence over project settings for conflicting keys.
The `permissions` field is the most impactful part of settings.json. It controls which tool calls Claude can make without pausing to ask for confirmation. By default, Claude asks before writing files, running bash commands, or calling external APIs. You can pre-approve specific patterns (e.g., 'allow all npm commands') to make Claude faster on tasks you trust it with.
The `mcpServers` field wires up Model Context Protocol servers — external processes that give Claude new tools (database queries, Slack messages, GitHub API, custom APIs). Each entry maps a server name to its startup command and environment variables. Claude automatically discovers and calls these tools in sessions.
Environment variables can be set in settings.json under `env` — useful for API keys that Claude needs to call external services (not your ANTHROPIC_API_KEY, which is handled separately). Values set here are available to bash tool calls and MCP servers spawned by Claude Code.
The `model` field lets you pin a specific Claude model for the project. If your project needs consistent behavior across the team, pinning to `claude-sonnet-4-5` prevents individuals from inadvertently running expensive Opus sessions. Individual team members can override via `~/.claude/settings.json` or the CLAUDE_MODEL env var.
Hook definitions also live in settings.json under the `hooks` key. Each hook specifies an event type (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionStop) and a shell command to run. This is how you add automated behaviors — like auto-formatting after every file write or injecting git status into every prompt.
Examples
{
"model": "claude-sonnet-4-5",
"permissions": {
"allow": [
"Bash(npm:*)",
"Bash(pnpm:*)",
"Bash(git status)",
"Bash(git diff:*)",
"Bash(git add:*)",
"Bash(git commit:*)",
"Read",
"Write",
"Edit"
],
"deny": [
"Bash(rm -rf:*)",
"Bash(sudo:*)"
]
},
"env": {
"NODE_ENV": "development",
"DATABASE_URL": "postgresql://localhost:5432/myapp_dev"
},
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
}
},
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"command": "npx prettier --write $CLAUDE_TOOL_OUTPUT_PATH 2>/dev/null || true"
}
]
}
}{
"model": "claude-sonnet-4-5",
"permissions": {
"allow": [
"Bash(npm:*)",
"Bash(git:*)",
"Read",
"Write",
"Edit"
]
}
}{
"model": "claude-opus-4-5",
"permissions": {
"allow": [
"Bash(*)"
]
},
"env": {
"GITHUB_TOKEN": "ghp_your_personal_token_here"
}
}Tips
- →Commit `.claude/settings.json` to git but add `.claude/settings.local.json` to .gitignore — the local file is for personal overrides (personal API tokens, personal model preferences) that shouldn't be shared.
- →Use pattern matching in allow/deny — `Bash(git:*)` approves all git subcommands instead of listing each one individually.
- →The deny list is evaluated after allow. If you allow `Bash(*)` and deny `Bash(sudo:*)`, sudo is still blocked — deny wins.
- →MCP server env values support `${ENV_VAR}` interpolation — store secrets in your shell profile and reference them by name in settings.json to avoid committing credentials.
- →Test your settings by running `claude --debug` which prints the effective merged settings at startup.
- →Use `"model": "claude-haiku-4-5"` in CI settings.json to reduce costs on automated tasks while keeping Sonnet for interactive developer sessions.
FAQ
Where exactly does settings.json live?+
Project settings: `.claude/settings.json` in your repository root (alongside .git/). User settings: `~/.claude/settings.json` in your home directory. There's also `.claude/settings.local.json` for machine-specific project overrides that you add to .gitignore.
What's the difference between settings.json and CLAUDE.md?+
settings.json controls Claude Code's behavior — what tools it can use, which model to call, what MCP servers to connect. CLAUDE.md provides content — project context, coding conventions, docs. Think of settings.json as the permissions and config layer, CLAUDE.md as the knowledge layer.
Can I use environment variable references in settings.json?+
Yes, in the `env` and MCP server env fields you can use `${VAR_NAME}` syntax to reference environment variables from your shell. This is the right way to handle secrets — put them in your shell profile, not hardcoded in settings.json.
If I set permissions in settings.json do I ever see confirmation prompts?+
You'll only see prompts for tool calls not covered by your allow list. If you allow `Bash(npm:*)` you'll never be asked to confirm npm commands. If Claude tries `Bash(make build)` and make isn't in your allow list, it will pause and ask. Add it to the allow list to stop the interruption.
How do MCP servers in settings.json relate to the MCP tool calls I see in sessions?+
Each entry in `mcpServers` is a process that Claude Code starts when you begin a session. That process registers tools (e.g., 'query_database', 'create_github_pr') that Claude can call during the session. The process stays running for the session duration and is killed when the session ends.