Settings.json Schema — Claude Cert Academy

Settings.json Schema

Claude Code reads settings from settings.json (project or global) at startup. All keys are optional. Unknown keys are ignored.

Annotated Full Schema

{
  // Model to use by default. Overridden by --model flag.
  "model": "claude-opus-4-8",

  // Permission controls
  "permissions": {
    // Mode: "default" (prompt per tool), "auto" (no prompts), or "plan" (plan only)
    "mode": "default",

    // Tools (or tool+pattern) to allow without prompting in default mode
    "allow": [
      "Read",
      "Bash(npm test)",
      "Bash(npm run *)"
    ],

    // Tools (or tool+pattern) to block in all modes
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)",
      "Write(migrations/**)"
    ]
  },

  // Hooks: shell scripts invoked at agent lifecycle events
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": { "tool_name": "Bash" },
      "command": "/usr/local/bin/bash-guard.sh"
    },
    {
      "event": "PostToolUse",
      "command": "/usr/local/bin/audit-logger.sh"
    }
  ],

  // MCP server configurations
  "mcp": {
    "servers": [
      {
        "name": "my-db",
        "transport": "stdio",
        "command": "/usr/local/bin/mcp-db",
        "args": ["--config", "/etc/mcp/db.json"],
        "env": { "DB_URL": "postgres://localhost/mydb" }
      }
    ]
  },

  // Environment variables injected into every Claude Code session
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

Key Fields Reference

• model — string. Claude model ID. Default: latest recommended model.
• permissions.mode — string. One of: default, auto, plan. Default: default.
• permissions.allow — array of strings. Tool names or ToolName(pattern) pairs. Allowed without prompting in default mode.
• permissions.deny — array of strings. Tool names or ToolName(pattern) pairs. Always blocked.
• hooks — array of hook objects. Each has: event (string), matcher (optional object), command (string, absolute path).
• mcp.servers — array of MCP server objects. See MCP Configuration Reference for full server schema.
• env — object. Key-value pairs injected into the Claude Code process environment for every session.

settings.json vs. settings.local.json

• settings.json — committed to the repository. Shared by all team members. Put team conventions, MCP server names, permission defaults, and hook registrations here.
• settings.local.json — not committed (add to .gitignore). Machine-specific and per-user. Put API keys, MCP server credentials, personal model overrides, and env vars with secrets here.
• Merge order: settings.local.json values override settings.json values for the same keys. Both files are active simultaneously.
• Global scope: ~/.claude/settings.json and ~/.claude/settings.local.json apply to all projects for this user, at the lowest precedence.

Never put ANTHROPIC_API_KEY or other secrets in settings.json. It is committed to the repo and visible to all contributors. Use settings.local.json or your shell profile instead.

Server-Managed Settings

• Server-managed settings are pushed by an organization's central Claude Code management server (enterprise feature).
• They override both settings.json and settings.local.json for the matching keys.
• They appear in /config output as read-only (cannot be overridden locally).
• Common use: enforce deny rules for production write commands across all developer machines, or mandate a specific model for all org sessions.

Example: Complete Team settings.json

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "mode": "default",
    "allow": [
      "Read",
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(git push --force*)",
      "Bash(DROP TABLE*)",
      "Write(migrations/**)"
    ]
  },
  "hooks": [
    {
      "event": "PreToolUse",
      "matcher": { "tool_name": "Write", "tool_input.file_path": "migrations/**" },
      "command": "/usr/local/bin/migration-guard.sh"
    },
    {
      "event": "Stop",
      "command": "/usr/local/bin/session-audit.sh"
    }
  ],
  "mcp": {
    "servers": [
      {
        "name": "internal-docs",
        "transport": "http",
        "url": "https://mcp.internal.example.com/v1",
        "headers": { "Authorization": "Bearer ${INTERNAL_MCP_TOKEN}" }
      }
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

Pair settings.json with a settings.local.json.example file committed to the repo. The example shows which env vars to set (with placeholder values) so teammates know what to configure locally without exposing real credentials.

Continue to Claude Cert Academy