Getting Claude Code installed is the easy part. The real power comes from configuration, choosing the right model, setting up MCP servers, managing tool permissions, and switching between API providers.

This guide covers everything from basic API setup to advanced configuration, plus a deep dive into CC Switch, the 57K-star desktop app that turns multi-tool provider management from a headache into a one-click operation.

Part 1: Claude Code Native Configuration

API Key Setup

Two authentication paths:

OAuth (for Claude Pro / Max subscribers):

claude config

Completes a one-time browser login. Recommended for most users.

Environment Variable (for API key users):

# Set for current session
export ANTHROPIC_API_KEY="your-api-key-here"

# Make persistent (add to shell profile)
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

Model Selection

Set your default model via environment variable:

# Sonnet 4.6 — best daily coding model (recommended)
export ANTHROPIC_MODEL="claude-sonnet-4-6"

# Opus 4.6 — state-of-the-art, 1M context, agent teams
export ANTHROPIC_MODEL="claude-opus-4-6"

# Opus 4.5 — previous gen, enhanced Plan Mode
export ANTHROPIC_MODEL="claude-opus-4-5-20251101"

# Opus 4 — previous generation
export ANTHROPIC_MODEL="claude-opus-4-20250514"

# Haiku 3.5 — fastest, cheapest (limited capabilities)
export ANTHROPIC_MODEL="claude-3-5-haiku-20241022"

Or specify when launching:

claude --model claude-sonnet-4-6

Switching Models Mid-Session

Use the /model command inside a Claude Code session:

/model

This opens an interactive menu:

OptionDescription
DefaultOpus 4.6 with automatic Sonnet fallback
OpusOpus 4.6 for maximum capability
SonnetSonnet 4.6 for daily use
Opus Plan ModeOpus for research/planning, Sonnet for implementation

Opus 4.6 Plan Mode is particularly powerful — it uses the 1M context window and adaptive thinking for research, then hands off to Sonnet for execution. This gives you the best of both models while managing costs.

Configuration File Locations

Claude Code reads settings from multiple locations, with later entries overriding earlier ones:

FileScopeNotes
~/.claude.jsonGlobalRecommended — single source of truth
~/.claude/settings.jsonUser-globalPer-user defaults
~/.claude/settings.local.jsonUser-localLocal overrides (gitignored)
.claude/settings.local.jsonProject-localPer-project config
.mcp.jsonProject-scopedMCP servers, version-controlled

Best practice: Use ~/.claude.json for your primary config. It’s reliable, well-documented, and avoids confusion from scattered settings files.

Part 2: MCP Server Configuration

Model Context Protocol (MCP) lets Claude Code connect to external tools — file systems, databases, APIs, memory stores, and more.

Basic MCP Setup

Add servers to ~/.claude.json:

{
 "projects": {
 "/path/to/your/project": {
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
 },
 "memory": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-memory"]
 },
 "fetch": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-fetch"]
 }
 }
 }
 }
}

Project-Scoped MCP (Team Sharing)

Create .mcp.json in your project root to share MCP config via version control:

{
 "mcpServers": {
 "memory": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-memory"]
 },
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"]
 }
 }
}

Then enable it in .claude/settings.json:

{
 "enableAllProjectMcpServers": true
}

Or whitelist specific servers only:

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

Part 3: Tool Permissions

Allowed Tools

Control which tools Claude Code can use:

{
 "projects": {
 "/path/to/project": {
 "allowedTools": [
 "Task",
 "Bash(git log:*)",
 "Glob",
 "Grep",
 "LS",
 "Read",
 "Edit",
 "MultiEdit",
 "Write",
 "WebFetch"
 ]
 }
 }
}

Security note: "Bash" without restrictions grants access to all shell commands. Prefer pattern-restricted versions like "Bash(git log:*)" or "Bash(npm test:*)".

Interactive Permission Management

Use the /permissions command inside Claude Code for a visual permissions UI:

/permissions

This lets you:

  • View all currently allowed and denied tools
  • Grant or revoke access in real-time
  • No need to restart or edit JSON files

Disabling Tools

Block specific tools:

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

Note: Disabling MCPSearch forces all MCP tools to preload upfront. This increases context usage but avoids dynamic tool loading delays.

Part 4: Advanced Settings

Extended Workspace

Work across multiple directories without switching sessions:

# At startup
claude --add-dir /path/to/other/project

# Mid-session
/add-dir ../backend-api
/add-dir ~/shared/libraries

Use cases:

  • Frontend + backend in the same session
  • Referencing shared libraries or config repos
  • Dynamically expanding workspace as needs emerge

Session Names

Tag sessions for easy identification:

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

Environment Variables

VariableDescription
CLAUDE_CODE_DISABLE_1M_CONTEXTUse standard context instead of 1M
CLAUDE_CODE_DISABLE_CRONStop cron jobs from running mid-session
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MSTimeout for SessionEnd hooks (ms)
ENABLE_CLAUDEAI_MCP_SERVERSSet to false to disable claude.ai MCP servers

UI Settings

Disable loading spinner tips for a cleaner interface:

{
 "spinnerTipsEnabled": false
}

Part 5: CC Switch — The All-in-One Manager

CC Switch is a 57K-star open-source desktop app that manages five AI coding CLI tools from a single interface: Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw.

Why CC Switch?

Each CLI tool has its own configuration format — Claude Code uses JSON, Codex uses TOML, Gemini uses .env files. Switching API providers means manually editing different files across different locations. CC Switch eliminates all of that.

What you get:

FeatureDescription
One-click switching50+ built-in provider presets; paste your key, click switch
System traySwitch providers from the tray menu without opening the app
Unified MCPManage MCP servers across 4 apps with bidirectional sync
Skills marketplaceBrowse and install Claude skills from GitHub repos
Prompt managementMarkdown editor syncing CLAUDE.md / AGENTS.md / GEMINI.md
Local proxyHot-switching, auto-failover, circuit breaker, health monitoring
Usage trackingDashboard with spending, tokens, requests, and trend charts
Session managerBrowse, search, restore conversation history across all apps
Cloud syncSync configs via Dropbox, OneDrive, iCloud, or WebDAV

Installing CC Switch

macOS (Homebrew — Recommended):

brew tap farion1231/ccswitch
brew install --cask cc-switch

Update:

brew upgrade --cask cc-switch

Windows:

Download CC-Switch-v{version}-Windows.msi from GitHub Releases.

Arch Linux:

paru -S cc-switch-bin

Other Linux:

Download .deb, .rpm, or .AppImage from GitHub Releases:

  • .deb for Debian/Ubuntu
  • .rpm for Fedora/RHEL/openSUSE
  • .AppImage for universal

System Requirements

PlatformMinimum
WindowsWindows 10+
macOSmacOS 12 (Monterey)+
LinuxUbuntu 22.04+ / Debian 11+ / Fedora 34+

Quick Start

  1. Add a provider — Click “Add Provider” → Choose from 50+ presets or create custom
  2. Paste your API key — Enter your key, confirm endpoint
  3. Switch — Click “Enable” in the main UI, or right-click tray icon for instant switch
  4. Restart terminal — Changes take effect (Claude Code supports hot-switching — no restart needed)

Key Workflow: Multi-Provider Switching

The most common use case is switching between:

  • Official Anthropic API (direct)
  • AWS Bedrock (enterprise)
  • Google Vertex AI (enterprise)
  • Third-party relays (cost optimization)

With CC Switch, this is literally one click. No more editing JSON files, no more remembering which env variable goes where.

MCP Management

CC Switch provides a unified MCP panel across all supported CLI tools:

  • Add MCP servers from templates or custom config
  • Toggle per-app sync (e.g., enable a server for Claude Code but not Codex)
  • Import via Deep Link — paste a ccswitch:// URL to import a complete MCP config
  • Bidirectional sync — changes in CC Switch reflect in live config files and vice versa

Skills Marketplace

Browse, install, and manage Claude Code skills (reusable prompt packages):

  • One-click install from GitHub repos or ZIP files
  • Custom repository management
  • Supports symlink and file copy
  • Install skills to all apps simultaneously

Proxy & Failover

CC Switch includes a built-in local proxy:

  • Hot-switching — change providers without restarting
  • Auto-failover — automatically fall back to backup providers when the primary fails
  • Circuit breaker — protects against repeated failures
  • Health monitoring — track provider latency and availability
  • Per-app routing — independently proxy Claude, Codex, or Gemini

Where CC Switch Stores Data

PathContent
~/.cc-switch/cc-switch.dbSQLite database (providers, MCP, prompts, skills)
~/.cc-switch/settings.jsonDevice-level UI preferences
~/.cc-switch/backups/Auto-rotated backups (keeps 10 most recent)
~/.cc-switch/skills/Installed skills (symlinked to apps)

CC Switch CLI Fork

If you prefer a terminal-only workflow, check out cc-switch-cli — a CLI fork with the same provider management capabilities:

cc-switch provider list # List providers
cc-switch provider switch <id> # Switch provider
cc-switch --app claude provider list # Manage Claude providers
cc-switch --app codex mcp sync # Sync Codex MCP servers
cc-switch --app gemini prompts list # List Gemini prompts

Supports the same 5 apps and includes WebDAV sync compatibility with the desktop version.

How I Actually Use This Stack

Before CC Switch, I was editing .claude.json by hand every time I wanted to switch between Anthropic’s API and a third-party relay. I kept breaking the JSON with trailing commas. CC Switch turned that into a tray-menu click, and that alone justified the install.

My daily setup: Sonnet 4.6 as the default, Opus Plan Mode when I need to reason through a tricky architecture problem. For MCP, I settled on three servers — memory, fetch, and filesystem. I originally loaded ten (GitHub, Brave search, Puppeteer, the whole catalog), but noticed my startup costs creeping up. Each server adds context tokens, and at 20 sessions a day, those pennies became dollars. Three servers turned out to be enough for 90% of my work.

One hard lesson: I left "Bash" unrestricted in allowed tools during my first week. Claude ran rm -rf on a test directory that had uncommitted work in it. Now I use pattern-restricted permissions like "Bash(git log:*)" and "Bash(npm test:*)" exclusively. The five minutes spent configuring those restrictions saved me from a genuinely painful data loss.

Here’s the configuration stack we use in production:

LayerToolPurpose
Provider managementCC SwitchSwitch between API providers, manage keys
ModelSonnet 4.6 (daily) / Opus Plan Mode (complex)Balance cost vs capability
Token optimizationCaveman + RTKSave 50–90% on token costs
Project intelligenceOpenWolfPersistent memory, hooks, file indexing
MCP serversmemory + fetch + filesystemExternal tool integration
Config approach~/.claude.json + .mcp.json per projectGlobal defaults + project-specific MCP

Next Steps