Master Claude Code configuration with this comprehensive guide. From API keys and model selection to MCP servers and tool permissions, these settings unlock Claude Code's full potential for your development workflow.

API Key Setup​

To use Claude Code, a user must have a Claude Pro subscription, a Claude Max subscription, or an Anthropic API key. You can set it up with an API key by following these methods:

# Option 1: Environment variable (recommended)
export ANTHROPIC_API_KEY="your-api-key-here"

# Option 2: Add to your shell profile
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Model Selection​

Claude Code supports multiple models. You can specify which model to use:

Claude Sonnet 4.6: Best coding model with improved consistency and computer use

export ANTHROPIC_MODEL="claude-sonnet-4-6"

Claude Opus 4.6: State-of-the-art with 1M context, agent teams, adaptive thinking

export ANTHROPIC_MODEL="claude-opus-4-6"

Claude 4.5 Opus: Previous Opus with enhanced Plan Mode

export ANTHROPIC_MODEL="claude-opus-4-5-20251101"

Claude 4 Opus: Previous generation maximum capability model

export ANTHROPIC_MODEL="claude-opus-4-20250514"

Claude 3.5 Haiku: Fastest and most cost-effective

export ANTHROPIC_MODEL="claude-3-5-haiku-20241022"

Alternative Method: You can also specify the model directly when starting Claude Code:

claude --model claude-sonnet-4-6
claude --model claude-opus-4-6
claude --model claude-opus-4-5-20251101
claude --model claude-opus-4-20250514
claude --model claude-3-5-haiku-20241022

Model Switching During Session​

You can switch models mid-session using the /model command, which provides an interactive menu:

/model

Available Options:

1. Default (recommended) - Opus 4.6 with generous limits, automatic fallback to Sonnet 4.6 when needed
2. Opus - Opus 4.6 for state-of-the-art software engineering
3. Sonnet - Sonnet 4.6 for daily use
4. Opus Plan Mode - Use Opus in plan mode, Sonnet 4.6 otherwise

Opus 4.6 Plan Mode Features​

Opus 4.6 brings enhanced Plan Mode with:

• 1M context window - Analyze larger codebases during planning
• Adaptive thinking - Model decides when extended reasoning helps
• Agent teams - Multi-agent collaboration (research preview)
• Context compaction - Automatic summarization for longer sessions

The Opus Plan Mode automatically switches between models based on context, using Opus 4.6 for research and planning phases, then Sonnet 4.6 for implementation and execution.

Model Name Validation​

Starting with v1.0.111, the /model command validates provided model names to ensure they're correctly specified and supported. This prevents errors from typos or unsupported model requests:

/model claude-4-sonnet # Valid - switches successfully
/model invalid-model # Invalid - shows validation error
/model opus # Valid - uses model alias

Validation ensures immediate feedback rather than failing during actual model requests.

MCP Configuration​

Model Context Protocol (MCP) allows Claude Code to connect to external tools and services. Configure MCP servers to extend Claude's capabilities:

MCP Server Setup​

MCP configuration can be stored in multiple locations:

• Project-scoped MCP: .mcp.json (in your project directory, version-controlled)
• Project-specific: .claude/settings.local.json (in your project directory)
• User-specific local: ~/.claude/settings.local.json
• User-specific global: ~/.claude/settings.json
• Main Claude.json: ~/.claude.json
• Dedicated MCP file: ~/.claude/mcp_servers.json

Example MCP configuration:

// Example: ~/.claude.json (recommended for reliability)
{
"projects":{
"/path/to/your/project":{
"mcpServers":{
"filesystem":{
"command":"npx",
"args":["-y","@modelcontextprotocol/server-filesystem","/Users/username/Desktop","/path/to/allowed/dir"]
},
"memory":{
"command":"npx",
"args":["-y","@modelcontextprotocol/server-memory"]
},
"fetch":{
"command":"npx",
"args":["-y","@modelcontextprotocol/server-fetch"]
}
}
}
},
 ...
}

Note: If following this example ensure you update the right projects configuration.

For additional tools and integrations beyond MCP, explore our Add-ons.

Project-Scoped MCP Configuration​

Project-scoped MCP configuration uses .mcp.json files in your project directory, enabling version-controlled, team-shared MCP server definitions.

Benefits:

• Team Collaboration - Share MCP configurations via version control
• Project Isolation - Different projects can have different MCP setups
• Simplified Onboarding - New team members get MCP servers automatically
• Version Control - Track changes to MCP configurations alongside code

Example .mcp.json:

{
"mcpServers":{
"reddit":{
"command":"node",
"args":["/Users/username/reddit/build/index.js"]
},
"memory":{
"command":"npx",
"args":["-y","@modelcontextprotocol/server-memory"]
}
}
}

Project MCP Server Control:

To enable project-scoped MCP servers, add one of these settings to your .claude/settings.json:

{
"enableAllProjectMcpServers":true
}

Automatically approves ALL MCP servers defined in project .mcp.json files

{
"enabledMcpjsonServers":["memory","github"]
}

Whitelist specific servers from .mcp.json files to approve

{
"disabledMcpjsonServers":["filesystem"]
}

Blacklist specific servers from .mcp.json files to reject

Choose the approach that best balances convenience with your security requirements.

UI Settings​

Configure Claude Code's interface behavior and visual elements to match your workflow preferences.

Spinner Tips Configuration​

Control whether helpful tips appear during loading animations by adding the setting to your project's .claude/settings.json:

{
"spinnerTipsEnabled":false// Disable spinner tips for cleaner interface
}

Benefits of disabling:

• Reduced visual distractions during focused work
• Cleaner interface for minimalist preferences
• Faster visual processing without constant tip notifications

CLI Flags​

Session Name Flag (v2.1.76+)​

Set a display name for your session at startup:

claude -n "feature-auth"
claude --name "bug-fix-123"

This name appears in session lists and helps identify sessions when running multiple instances.

Attribution Settings​

Control how Claude Code attributes its contributions to commits and pull requests (v2.0.62):

{
"attribution":{
"commits":true,// Include Co-Authored-By in commits
"pullRequests":true// Include Claude Code footer in PRs
}
}

Note: This setting deprecates the previous includeCoAuthoredBy option. See Attribution Setting FAQ for migration details.

Allowed Tools​

Allowed Tools Setup​

Allowed tools configuration can be stored in multiple locations:

• Project-specific: .claude/settings.local.json (in your project directory)
• User-specific local: ~/.claude/settings.local.json
• User-specific global: ~/.claude/settings.json
• Main Claude.json: ~/.claude.json

Example Allowed Tools configuration:​

// Example: ~/.claude.json (recommended for reliability)
{
"projects":{
"/path/to/your/project":{
"mcpServers":{
"filesystem":{
"command":"npx",
"args":["-y","@modelcontextprotocol/server-filesystem","/Users/username/Desktop","/path/to/allowed/dir"]
}
},
"allowedTools":[
"Task",
"Bash",// ⚠️ Dangerous: allows all system commands
"Bash(git log:*)",// Safer: only allows git log commands
"Glob",
"Grep",
"LS",
"Read",
"Edit",
"MultiEdit",
"Write",
"WebFetch",
"WebSearch"
]
}
},
 ...
}

Note: If following this example ensure you update the right projects configuration.

Interactive Permission Management​

For a more user-friendly approach to managing tool permissions, use the /permissions command within Claude Code:

# Launch the interactive permissions UI
/permissions

This advanced interface allows you to:

• View current permissions - See which tools are currently allowed or denied
• Explicitly allow tools - Grant permission to specific tools or tool patterns
• Explicitly deny tools - Block access to tools you want to restrict
• Navigate visually - Use an intuitive UI instead of manually editing JSON files

The /permissions interface provides real-time permission management with a fluid, responsive experience that makes configuration changes effortless—no need to restart Claude Code or manually edit configuration files.

Advanced Settings​

Sandbox Settings (v2.1.77+)​

allowRead - Re-allow read access in directories blocked by denyRead:

{
"allowRead":["/path/to/allowed/subdir"]
}

Useful for granting access to specific subdirectories within a broader denied region.

Worktree Settings (v2.1.76+)​

worktree.sparsePaths - Checkout only specific directories in worktrees:

{
"worktree":{
"sparsePaths":["packages/my-service","shared/common"]
}
}

Improves performance for large monorepos. See Worktree Isolation.

Memory Settings (v2.1.74+)​

autoMemoryDirectory - Custom storage location for auto-memory files:

{
"autoMemoryDirectory":"/custom/path/to/memory"
}

Model Settings (v2.1.73+)​

modelOverrides - Map model picker selections to custom provider IDs:

{
"modelOverrides":{
"sonnet":"custom-provider/sonnet-4-6",
"opus":"custom-provider/opus-4-6"
}
}

Enterprise Settings (v2.1.76+)​

feedbackSurveyRate - Sample rate for feedback surveys (0.0 to 1.0):

{
"feedbackSurveyRate":0.1
}

Disallowed Tools​

Block specific tools from being used in Claude Code sessions using the disallowedTools setting:

{
"disallowedTools":["MCPSearch","WebSearch"]
}

Disabling Tool Search​

Tool Search (v2.1.7) dynamically loads MCP tools when they exceed 10% of your context window. To disable this and preload all MCP tools upfront:

{
"disallowedTools":["MCPSearch"]
}

Note: Disabling Tool Search increases context usage for users with many MCP servers configured.

Additional Working Directories / Extended Workspace​

Claude Code can access multiple directories beyond your current working directory using:

• CLI argument: --add-dir (added in v1.0.18) when starting Claude Code
• Slash command: /add-dir mid-session for seamless workflow expansion

This allows you to work across multiple projects or reference external resources without changing directories or restarting your session.

Usage​

CLI Argument (at startup):

# Add a single additional directory
claude --add-dir /path/to/other/project

# Combine with other options
claude --add-dir ~/shared/libraries

# Use with print mode for scripting
claude --add-dir ../backend -p "Validate that API calls in the current directory match endpoints defined in ../backend"

Slash Command (mid-session):

# Add directory without restarting your session
/add-dir /path/to/other/project

# Add multiple directories as needed
/add-dir ~/shared/libraries
/add-dir ../backend-api

Common Use Cases​

Multi-Repository Projects

# At startup: Work on frontend while referencing the backend API
claude --add-dir ../backend-api

# Mid-session: Add backend when you need to reference API endpoints
/add-dir ../backend-api

Shared Resources

# At startup: Access shared configs or documentation
claude --add-dir ~/company/shared-configs

# Mid-session: Add shared resources when needed
/add-dir ~/company/shared-configs

Dynamic Workflow expansion

# Start with current project, then expand as needed
# No need to restart when you realize you need additional context
/add-dir ../related-service
/add-dir ~/templates

Note: The current working directory is always included. CLAUDE.md files appear to not be read in automatically from additional directories added via --add-dir.

Environment Variables​

Configure Claude Code behavior through environment variables:

Context and Performance​

Hooks and Sessions​

MCP Integration​

Example Usage:

# Disable 1M context window
export CLAUDE_CODE_DISABLE_1M_CONTEXT=true

# Disable cron jobs
export CLAUDE_CODE_DISABLE_CRON=true

# Increase SessionEnd hook timeout to 30 seconds
export CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000

# Opt out of claude.ai MCP servers
export ENABLE_CLAUDEAI_MCP_SERVERS=false

See Also: Pricing Plans|CLAUDE.md Guide|MCPs & Add-ons|FAQs