Повна конфігурація settings.json

Claude Code читає налаштування з чотирьох файлів (user, shared project, project local і managed-settings.json); організація може доставляти managed-налаштування й іншими механізмами. Окремий файл ~/.claude.json Claude Code пише сам для себе. Нічого з цього не створюється при встановленні: файл з’являється, коли ти змінюєш опцію в /config або даєш постійний дозвіл у запиті прав.

Файли і області

Де саме лежить local-файл. У git-репозиторії його читають і пишуть у корені репо (у worktree — корінь основного checkout), з v2.1.211. Він лишається поруч із .claude/settings.json, якщо проєкт поза git, корінь репо — це $HOME, ОС — Windows або корінь/.git/.claude належать не вам. Старий файл у стартовій теці ще читається (при конфлікті виграє корінь; правила прав зливаються з обох). Перший запис додає **/.claude/settings.local.json у глобальні git excludes (core.excludesFile, інакше $XDG_CONFIG_HOME/git/ignore або ~/.config/git/ignore); файл, створений руками, до .gitignore додай сам. Його allow-правила не чекають довіри, поки файл не під git.

Спільний .claude/settings.json читається з основної робочої теки сесії: щоб діяв файл у корені репо, запускай Claude Code саме там. Після /cd обидва проєктні файли читаються з нової теки (v2.1.246+).

Managed: звідки і де лежить

У каталозі файлів лежать managed-settings.json, необов’язковий managed-settings.d/*.json і managed-mcp.json. Старий C:\ProgramData\ClaudeCode\managed-settings.json не читається. Шаблони для Jamf, Iru, Intune і Group Policy є в репозиторії anthropics/claude-code (examples/mdm). Є ще parent settings — managed-налаштування від процесу-хоста (опція managedSettings в Agent SDK, Claude Desktop); керує ними parentSettingsBehavior.

Порядок пріоритету

1. Managed — нічим не перевизначається (з винятками нижче). Managed model — стартовий default, а не замок: замки це availableModels і deniedModels.
2. Командний рядок --settings <файл-або-JSON> — лише на цю сесію. Інші прапори (--model) задають одну річ і не входять у стек.
3. Project local .claude/settings.local.json.
4. Shared project .claude/settings.json.
5. User ~/.claude/settings.json.

Змінні середовища — не рівень стека. Для кожної пари «змінна ↔ ключ» вирішено окремо: ANTHROPIC_MODEL перебиває ключ model з будь-якого файлу, а ANTHROPIC_DEFAULT_MODEL діє, лише якщо жоден файл не задає model. Блок env у файлі — звичайний ключ, що йде за рівнями вище.

Порядок усередині managed

1. Remote / server-managed — лише коли сесія автентифікується прямо в Anthropic прийнятним credential або входить у gateway через /login. На інших провайдерах чи з іншим ANTHROPIC_BASE_URL починається з наступного пункту.
2. MDM — plist або HKLM.
3. Файли — managed-settings.json разом з managed-settings.d/*.json.
4. HKCU — лише коли вище немає жодного admin-документа (документ «присутній», якщо задає будь-який ключ політики не-null, навіть нечитабельний, або якщо HKLM-значення / файл / каталог існує, але нечитабельний).

managedSourcesBehavior

Ключі, що читаються з усіх admin-джерел навіть при first-wins (HKCU у цьому скануванні не бере участі): замки sandbox.network.allowManagedDomainsOnly і sandbox.filesystem.allowManagedReadPathsOnly; allowAllClaudeAiMcps; allowManagedMcpServersOnly; deniedMcpServers і disableClaudeAiConnectors (v2.1.273+); sandbox.bwrapPath, socatPath, ripgrep; sandbox.filesystem.disabled, sandbox.network.strictAllowlist; useAutoModeDuringPlan, syncClaudeAiSkills, syncClaudeAiPlugins (false з будь-якого); enableArtifact; maxEffortLevel (найнижча стеля); відмова від commit-trailer у attribution; forceRemoteSettingsRefresh; env по змінних. Ключі gateway-входу (forceLoginGatewayUrl, gatewayInternalNetworks, "gateway") ніколи не читаються з server-managed.

Розбиття політики на файли: managed-settings.d

Якщо частинами політики володіють різні команди, поклади кожну в окремий файл у managed-settings.d/ поруч з managed-settings.json. Спершу зливається managed-settings.json, потім усі *.json в алфавітному порядку (префікси 10-telemetry.json, 20-security.json); приховані файли й не-.json ігноруються.

Правила злиття між user / project / local / --settings

• Скаляри: виграє файл вищого пріоритету.
• Списки (permissions.allow/deny/ask, масиви sandbox, allowedHttpHookUrls, httpHookAllowedEnvVars, allowedMcpServers/deniedMcpServers): об’єднуються, кожен файл лише додає.
• Винятки зі злиття: fallbackModel (весь ланцюг з найвищого файлу), modelPicker (цілком з найвищого з managed, --settings, user; у project/local ігнорується), availableModels (managed-список застосовується як є, не-managed області зливаються), modelSettings (по моделях разом з effortLevel), extraKnownMarketplaces (однойменний запис вищого файлу замінює цілком, з v2.1.228).
• hooks зливаються між файлами, а hooks з managed видалити не можна.
• Довіра до робочої теки: у проєктному файлі лише після довіри діють permissions.allow, additionalDirectories, extraKnownMarketplaces, більшість env, hooks / statusLine / fileSuggestion і project apiKeyHelper. Правила deny і ask діють одразу.

Винятки: коли нижчий рівень сильніший за managed

Для ключів-обмежень Claude Code шанує суворіше значення навіть з області, яка інакше не може перевизначити managed.

Окремий виняток — застосунок-хост, що задає CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST: його модельна конфігурація перекриває managed-ключі model, fallbackModel, modelPicker, modelOverrides та змінні вибору моделі в managed env; managed availableModels лишається в силі, якщо хост не дає свій.

Де що тримати: Django + Vue команда

{
  "permissions": {
    "allow": ["Bash(python manage.py test *)", "Bash(npm run lint)", "Bash(npm run test:unit *)"],
    "deny": ["Read(./.env)", "Bash(python manage.py flush *)"]
  },
  "env": {
    "DJANGO_SETTINGS_MODULE": "config.settings.dev"
  }
}

Як Claude Code ухвалює рішення про виклик інструмента

Правила дозволів виконує Claude Code, а не модель: інструкції в промпті чи CLAUDE.md впливають на те, що Claude намагається зробити, але не на те, що йому дозволено. Порядок такий:

1. Хуки PreToolUse запускаються перед запитом на підтвердження. Хук з exit code 2 зупиняє виклик ще до перевірки правил — навіть якщо збігається allow-правило і навіть у bypassPermissions. Рішення хука allow не обходить правила deny та ask.
2. Правила перевіряються в порядку deny → ask → allow. Виграє перше співпадіння, специфічність не має значення: широкий Bash(aws *) у deny блокує навіть виклик, який збігається з вужчим Bash(aws s3 ls) в allow.
3. Немає жодного збігу — вирішує режим дозволів (defaultMode): default питає, acceptEdits автоматично приймає редагування, dontAsk відхиляє, bypassPermissions пропускає.
4. Запобіжники, які не відключає жоден режим: явні ask-правила, rm/rmdir по «критичних шляхах» (корінь, домашня тека, робоча тека і її батьки), інструменти з requiresUserInteraction, AskUserQuestion.

«Yes, and don’t ask again» для Bash зберігає правило на постійно для репозиторію й команди (у .claude/settings.local.json у корені git-репозиторію, з v2.1.211). Для складеної команди зберігається окреме правило на кожну підкоманду, до 5 штук. Дозволи на редагування файлів діють лише до кінця сесії.

Синтаксис правил за типом інструмента

Загальна форма — Tool або Tool(специфікатор). Дужки всередині специфікатора літеральні, екранувати їх не треба. Bash(*) — те саме, що Bash.

Bash: wildcard-и, складені команди й обгортки

* у правилі Bash збігається з будь-яким текстом, включно з пробілами, і може стояти будь-де. Ставте * після підкоманди: для git log --oneline main програма — git, підкоманда — log, тому Bash(git log *) дозволяє лише git log, а Bash(git *) — усі git-команди. Для allow-правила з * перед підкомандою (Bash(git * main)) є попередження при старті.

• Кінцевий * (з пробілом) збігається й з «голою» командою (Bash(ls *) = ls), але лише якщо це єдиний wildcard у правилі. Пробіл перед * — частина правила.
• :* на кінці (Bash(ls:*)) — застарілий синонім кінцевого *; розпізнається лише в кінці шаблону. Діалог дозволів пише канонічну форму з пробілом.
• Складені команди. Роздільники: &&, ||, ;, |, |&, &, нові рядки. Allow-правило має збігатися з кожною підкомандою окремо; deny/ask спрацьовують, якщо збіглась будь-яка підкоманда, навіть всередині $(), підоболонки чи циклу for. Команда із завислим && на кінці вважається нерозбірною, і allow її не схвалює.
• Обгортки, які прибираються перед порівнянням: timeout, time, nice, nohup, stdbuf, command, builtin, zsh noglob, «голий» xargs (без прапорців). Відомі безпечні змінні середовища на початку (NODE_ENV=test npm test) прибираються для allow; для deny/ask правило збігається поверх будь-якого присвоєння.
• Не прибираються: direnv exec, devbox run, mise exec, npx, docker exec — Bash(devbox run *) збігається з devbox run rm -rf .. Пишіть правило з бігунком і внутрішньою командою: Bash(devbox run npm test). watch, setsid, ionice, flock і find -exec/-delete префіксним правилом не схвалюються.
• Завжди без запиту (набір вшитий, не налаштовується): ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd і read-only git. Щоб вимагати підтвердження — ask-правило. Все одно питають: нецитовані glob-и з небезпечними прапорцями, docker -H/--context, file -m/-f, UNC-шляхи, запис у PATH/IFS, нерозбірні команди та команди довші за 10 000 символів, cd + git, cd + редирект.
• Редиректи. Цілі >, >>, 2> перевіряються за правилами Edit, protected paths та робочими теками; ціль < — за правилами Read (з v2.1.257); цілі tee — з v2.1.269. /dev/null, 2>&1 та heredoc не перевіряються.

Read / Edit: шляхи у стилі gitignore

• Голе ім’я файла працює на будь-якій глибині: Read(.env) = Read(**/.env). Правило Read(//**/.env) закриває .env будь-де на диску. На Windows шляхи нормалізуються до /c/Users/...: //c/**/.env або //**/.env для всіх дисків.
• Однокомпонентна тека типу src/**: в allow збігається лише з <cwd>/src, у deny/ask — з текою src на будь-якій глибині. Якщо потрібна будь-яка глибина в allow — **/src/**.
• !-заперечення вирізає виняток із попередніх deny/ask того ж джерела (лише відносно cwd, не відкриває вміст цілком заблокованої теки).
• Deny на Read блокує також Edit і Write на тому шляху (Edit з v2.1.208, Write з v2.1.228); NotebookEdit не покривається — додайте deny на Edit. Файл .claudeignore нічого не робить.
• Read/Edit deny працюють для вбудованих файлових інструментів, для розпізнаних Bash-команд (cat, head, tail, sed, tee) і цілей редиректів, але не для grep -r pattern . чи скриптів, що самі відкривають файли. Для всіх процесів потрібен sandbox. Для симлінків allow потребує збігу і посилання, і цілі, а deny спрацьовує, якщо збігається будь-що одне.
• Ці правила живлять і sandbox: шляхи з Edit-allow потрапляють до sandbox.filesystem.allowWrite, Edit-deny — до denyWrite, Read-deny — до denyRead.

WebFetch: домени й «весь інтернет»

• WebFetch(domain:example.com) — точний хост; domain:*.example.com — піддомени будь-якої глибини, але не сам example.com. Wildcard у будь-якому іншому місці (example.*) охоплює лише один сегмент між крапками. Wildcard-и працюють з v2.1.172.

Тільки форма domain: потрапляє до мережевого allow/deny-списку sandbox, і sandbox враховує лише wildcard-и *.example.com та голий * (з v2.1.186); example.* на sandbox-команди не впливає. Зверніть увагу: заборона WebFetch не закриває мережу, якщо Bash дозволений — curl все одно дістанеться будь-якого URL.

Правила за параметром виклику

deny та ask (не allow) можуть збігатися з одним верхньорівневим скалярним параметром будь-якого вбудованого інструмента:

• Одне правило — один параметр; для двох умов пишіть два правила. Параметр, якого модель не передала, ніколи не збігається (Agent(model:*) не зачепить виклик без model). Значення підтримує *.
• Основні поля (command, file_path, path, notebook_path, url) так зіставити не можна: правило Bash(command:rm *) ігнорується з попередженням при старті.
• Для MCP-інструментів параметрні правила працюють лише через --disallowedTools; у файлах налаштувань будь-яке правило mcp__… з дужками пропускається.

Режими дозволів

Режим задає базову поведінку для викликів, яких не торкнулося жодне правило. Правила працюють поверх режиму: deny блокує в усіх режимах, включно з bypassPermissions, а allow у bypassPermissions не має ефекту. Перемикання в сесії — Shift+Tab; dontAsk у цикл не входить ніколи (лише --permission-mode dontAsk), bypassPermissions з’являється лише якщо сесію запущено з ним (або з --allow-dangerously-skip-permissions).

"allow": [
  "Bash(git status)", "Bash(git diff *)", "Bash(git log *)",
  "Bash(git add *)",
  "Bash(python manage.py showmigrations *)",  // без * збіглась би лише точна команда
  "Bash(npm run lint)", "Bash(npm run test:unit)",
  "Edit(/src/**/*.vue)",       // / = від кореня проєкту (у project settings), НЕ абсолютний
  "Edit(/src/**/*.ts)",
  "WebFetch(domain:docs.djangoproject.com)",
  "mcp__github__get_*"         // * лише в частині назви інструменту
]

"deny": [
  "Read(**/.env)", "Read(**/.env.*)",  // .env — ніколи
  "Read(~/.ssh/**)", "Read(~/.aws/**)",
  "Bash(sudo *)", "Bash(su *)",
  "Bash(rm -rf *)", "Bash(dd *)",   // без * правило — точний збіг
  "Bash(curl *)", "Bash(wget *)", "Bash(ssh *)",
  "mcp__*"                        // у deny можна glob по назві інструменту
]

"ask": [
  "Bash(git commit *)", "Bash(git push *)", "Bash(git merge *)",
  "Bash(python manage.py migrate)",
  "Bash(docker compose up *)", "Bash(docker compose down *)",
  "Bash(gh pr create *)"
]

"autoMode": {
  "environment": ["Django монорепо, prod-доступу з ноутбуків немає"],
  "allow":       ["$defaults", "запуск тестів і лінтерів"],
  "soft_deny":   ["$defaults", "зміни в міграціях"],
  "hard_deny":   ["$defaults", "будь-які дії з prod-базою"]
},
"disableAutoMode": "disable"   // повністю заборонити auto

"permissions": { "disableBypassPermissionsMode": "disable" }

"allowManagedPermissionRulesOnly": true

"additionalDirectories": [
  "../backend-api",
  "../docs/"
]

"permissions": { "blockReadsOutsideWorkingDirectories": true }

"autoMode": {
  "classifyAllShell": true
}

"useAutoModeDuringPlan": false

"skipDangerousModePermissionPrompt": true

"skipAutoPermissionPrompt": true

Робочі директорії

За замовчуванням Claude має доступ до теки, де запущений; це основна робоча тека сесії. Розширити доступ можна так:

• --add-dir <path> при старті, /add-dir у сесії або permissions.additionalDirectories у налаштуваннях. Файли там підкоряються тим самим правилам: читання без запиту, редагування — за режимом.
• /cd <path> переносить основну теку: підвантажує її CLAUDE.md, project-налаштування (правила й хуки), .mcp.json та плагіни нової теки. Для незнайомої теки показує діалог довіри. Обмежити цілі можна правилами Cd(...).
• Мережеві UNC-шляхи (\\server\share) додати не можна — на Windows підмонтуйте диск літерою.
• Теки з additionalDirectories дають лише доступ до файлів, не конфігурацію. З --add-dir підхоплюються .claude/skills, .claude/commands, .claude/agents та лише ключі enabledPlugins і extraKnownMarketplaces із settings; CLAUDE.md — тільки з CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Довіра до робочої теки (workspace trust)

• permissions.allow і additionalDirectories з .claude/settings.json проєкту діють лише після діалогу довіри. deny та ask діють одразу — вони тільки обмежують.
• claude -p і SDK діалог не показують: project allow-правила там не використовуються, хоча хуки з project-налаштувань — використовуються. Для чужого репозиторію запускайте з --setting-sources user або --bare.
• .claude/settings.local.json, який відстежується git (або симлінкований), вважається репозиторним: його правила чекають довіри.

Ключі, доступні лише в певних файлах

Приклад для Django + Vue команди

Налаштування проєкту, яке комітиться в .claude/settings.json. Зверніть увагу: allow-правила Bash з * після підкоманди; шляхи /backend/… і /frontend/… прив’язані до кореня проєкту; реальну заборону мережі дає sandbox, а не deny.

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)", "Bash(git add *)",
      "Bash(python manage.py check *)",
      "Bash(python manage.py showmigrations *)",
      "Bash(python manage.py makemigrations --dry-run *)",
      "Bash(pytest *)",
      "Bash(npm run lint *)", "Bash(npm run test:unit *)",
      "Edit(/backend/**/*.py)", "Edit(/frontend/src/**)",
      "WebFetch(domain:docs.djangoproject.com)", "WebFetch(domain:vuejs.org)"
    ],
    "ask": [
      "Bash(git commit *)", "Bash(git push *)",
      "Bash(python manage.py migrate *)",
      "Bash(docker compose *)",
      "Bash(dangerouslyDisableSandbox:true)"   // підтверджувати кожен вихід із sandbox
    ],
    "deny": [
      "Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)",
      "Read(~/.ssh/**)", "Read(~/.aws/**)",
      "Edit(/backend/config/settings/production.py)",
      "Bash(sudo *)", "Bash(rm -rf *)"
    ],
    "additionalDirectories": ["../shared-ui"],       // діє після довіри до теки
    "blockReadsOutsideWorkingDirectories": true
  }
}

"env": {
  "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
  // ↑ вимикає все нижче + /feedback, release notes, feature flags
  //   увага: "0" чи "false" теж ВИМИКАЮТЬ — щоб увімкнути, видали змінну
  "DISABLE_AUTOUPDATER": "1",     // фонові оновлення (claude update працює)
  "DISABLE_TELEMETRY": "1",       // вимкнути аналітику
  "DISABLE_ERROR_REPORTING": "1"  // вимкнути звіти про помилки
}

"env": {
  "ANTHROPIC_MODEL": "claude-sonnet-5-5",
  // ↑ перевизначає ключ model з будь-якого файлу
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
  // ↑ на що вказує аліас haiku + фонові задачі
  //   (замість deprecated ANTHROPIC_SMALL_FAST_MODEL)
  "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet"
  // ↑ лише fallback: model у frontmatter агента важливіший
  //   CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 — перебити все
}

"env": {
  "BASH_DEFAULT_TIMEOUT_MS": "300000",
  // ↑ таймаут bash команд у мс. Default 120000 (2 хв)
  //   стеля — BASH_MAX_TIMEOUT_MS, default 600000 (10 хв)
  "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "70",
  // ↑ % вікна для авто-стиснення — може лише ЗНИЗИТИ поріг
  "CLAUDE_CODE_EFFORT_LEVEL": "high"
  // ↑ low|medium|high|xhigh|max|auto — найвищий пріоритет
}

Як env взаємодіє з shell

• Значення в env перезаписує ту саму змінну, експортовану в shell. Між файлами діє звичайний пріоритет (див. файли і пріоритети), managed — найвищий.
• Виняток: якщо сесію запустили Claude Desktop або self-hosted runner, перемагає середовище запуску — env із файлів для змінних, які воно вже задало, ігнорується (debug-лог називає кожну).
• Щоб скасувати експорт зі shell, задай "": порожнє значення для вибору провайдера рахується як «не задано».
• NO_COLOR / FORCE_COLOR з env доходять лише до підпроцесів — кольори самого інтерфейсу міняй у shell до запуску.
• Значення лежать у файлі відкритим текстом і потрапляють у кожен підпроцес. Для OTLP-токена, що ротується, є otelHeadersHelper, для API-ключів — apiKeyHelper.
• Зміни в файлі підхоплюються працюючою сесією, але те, що читається лише на старті (наприклад, OpenTelemetry), чекає перезапуску; видалення змінної з файлу скасовується лише при наступному запуску.

Довідник змінних

В офіційній таблиці Variables документовано 390 змінних середовища. Нижче — близько п’ятдесяти тих, що справді потрібні в командній роботі, за групами. Повний перелік: code.claude.com/docs/en/env-vars.

Моделі, провайдер і автентифікація

Таймаути, повтори і Bash

Контекст, стиснення, пам’ять, кеш

Приватність і телеметрія

Мережа, проксі, сертифікати

MCP

Вимкнення функцій і службове

Що таке хук і як він налаштовується

Хук — це ваш код, який Claude Code виконує детерміновано на певній події життєвого циклу: shell-команда, HTTP-запит, виклик MCP-інструмента, промпт до моделі або міні-агент. На відміну від рядка в CLAUDE.md, це не прохання, а гарантія: формат після кожної правки, заборона на .env, тести перед завершенням відповіді. Конфігурація має три рівні вкладеності: подія → група з matcher → обробники.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-py.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Тут PostToolUse — подія, об’єкт із matcher — група (фільтр за назвою інструмента), внутрішній масив hooks — обробники, що виконуються паралельно. Коментарі й зайві коми в справжньому settings.json не допускаються.

Де визначати хуки

"PreToolUse": [{
  "matcher": "Bash",                // тільки назва інструмента
  "hooks": [{
    "type": "prompt",               // модель оцінює через Claude
    "if": "Bash(git push *)",       // фільтр за аргументами; збігається і з голим `git push`
    "prompt": "Чи безпечний цей push для main? Дані: $ARGUMENTS",
    "continueOnBlock": true,        // ok:false -> Claude бачить причину і коригується
    "timeout": 30
  }]
}]

"PostToolUse": [{
  "matcher": "Edit|Write",
  "hooks": [{
    "type": "command",
    "if": "Edit(*.py)",             // лише Python-файли (правила Edit(...) охоплюють усі вбудовані інструменти редагування)
    "command": "jq -r '.tool_input.file_path' | xargs ruff format",
    "async": true,                  // не блокує Claude (лише command); timeout для async не діє
    "statusMessage": "Форматую код..."
  }]
}]

"PostToolUse": [{
  "matcher": "Bash",
  "hooks": [{
    "type": "http",
    "url": "https://audit.company.com/log",
    "headers": { "Authorization": "Bearer $AUDIT_TOKEN" },
    "allowedEnvVars": ["AUDIT_TOKEN"]
    // ↑ лише ці змінні підставляються в headers; решта стає порожнім рядком
  }]
}]

"TaskCompleted": [{
  "hooks": [{
    "type": "command",
    "command": "cd "$CLAUDE_PROJECT_DIR" && python manage.py test --failfast 1>&2 || exit 2",
    // exit 2 = тести впали = задача не закривається
    "timeout": 120
  }]
}]

"Stop": [{
  "hooks": [{
    "type": "command",
    "command": "python3 ~/.claude/notify.py",
    "async": true,
    "statusMessage": "Відправляю сповіщення..."
  }]
}]

"InstructionsLoaded": [{
  "hooks": [{ "type": "command", "command": "jq -c . >> ~/.claude/audit.log", "async": true }]
}]

"disableAllHooks": false,          // default - хуки активні
"allowManagedHooksOnly": true      // лише managed settings

"allowedHttpHookUrls": ["https://audit.company.com/*", "http://localhost:*"]

"httpHookAllowedEnvVars": ["AUDIT_TOKEN", "HOOK_SECRET"]

Рецепти для Django + Vue + GitLab

Шість робочих заготовок. Скрипти кладемо в .claude/hooks/, робимо виконуваними (chmod +x) і комітимо разом із .claude/settings.json, щоб вся команда мала однакові правила. Шлях до скрипта — через ${CLAUDE_PROJECT_DIR} і "args": [] (exec form: без shell і без проблем з лапками).

1. ruff + black (і prettier для Vue) після правки

PostToolUse на Edit|Write. Скрипт сам відфільтровує розширення, тож не залежить від тонкощів if. Якщо після автовиправлень лишились порушення ruff, скрипт завершується з кодом 2: stderr побачить Claude (інструмент уже виконано, але зворотний зв’язок він отримає) і виправить решту.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh",
        "args": [],
        "timeout": 60,
        "statusMessage": "ruff + black / prettier..."
      }]
    }]
  }
}

#!/bin/bash
f=$(jq -r '.tool_input.file_path // empty')
f="${f//\\//}"                                   # Windows: \ -> /
cd "$CLAUDE_PROJECT_DIR" || exit 0
case "$f" in
  *.py)
    ruff check --fix --quiet "$f"
    black --quiet "$f"
    ruff check "$f" >&2 || exit 2                # залишились помилки -> Claude побачить stderr
    ;;
  *.vue|*.ts|*.js)
    npx prettier --write "$f" >/dev/null 2>&1
    ;;
esac
exit 0

2. Заборона правок .env та вже закомічених міграцій

PreToolUse на Edit|Write, exit 2. «Вже застосована» хук знати не може, тому використовуємо практичне наближення: міграція, що вже є в git, — незмінна; нову міграцію (файл, якого ще немає в індексі) створювати дозволено.

#!/bin/bash
f=$(jq -r '.tool_input.file_path // empty')
f="${f//\\//}"

case "$f" in
  */.env|*/.env.*|*/secrets/*)
    echo "Заблоковано: $f - секрети не редагуємо" >&2; exit 2 ;;
esac

if [[ "$f" == */migrations/0*.py ]] && \
   git -C "$CLAUDE_PROJECT_DIR" ls-files --error-unmatch "$f" >/dev/null 2>&1; then
  echo "Міграція $f вже в git. Не правте її - створіть нову через makemigrations" >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect.sh",
        "args": []
      }]
    }]
  }
}

3. pytest на Stop

Stop-хук запускає тести, лише якщо змінено .py-файли. Якщо тести падають, exit 2 не дає Claude зупинитись, а хвіст виводу pytest іде йому як причина. Після 8 поспіль таких продовжень Claude Code сам завершить хід; ліміт піднімає CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

#!/bin/bash
cd "$CLAUDE_PROJECT_DIR" || exit 0
[ -z "$(git status --porcelain -- '*.py')" ] && exit 0      # Python не чіпали
out=$(python -m pytest -x -q 2>&1) && exit 0
{ echo "pytest не пройшов, виправте перед завершенням:"; echo "$out" | tail -40; } >&2
exit 2

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pytest-on-stop.sh",
        "args": [],
        "timeout": 300,
        "statusMessage": "pytest..."
      }]
    }]
  }
}

4. Сповіщення, коли Claude чекає на вас

Подія Notification (matcher permission_prompt|idle_prompt). Варіант для Slack/Mattermost: webhook-URL береться зі змінної середовища, а не з репозиторію. Якщо потрібне лише системне сповіщення, скрипт може повернути terminalSequence (OSC 9/99/777 або BEL; працює тільки в інтерактивній сесії).

{
  "hooks": {
    "Notification": [{
      "matcher": "permission_prompt|idle_prompt",
      "hooks": [{
        "type": "command",
        "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/notify.sh",
        "args": [],
        "async": true
      }]
    }]
  }
}

#!/bin/bash
msg=$(jq -r '"Claude Code: " + (.message // "потрібна ваша увага")')
curl -fsS -X POST -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg t "$msg" '{text: $t}')" "$SLACK_WEBHOOK_URL"

#!/bin/bash
# варіант без мережі: OSC 777 (urxvt, Ghostty, Warp); для iTerm2/WezTerm - OSC 9, для Kitty - OSC 99
body=$(jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'      # тоді без "async": true

5. Аудит-лог дій Claude

Два варіанти. Локальний JSONL (швидко, нічого не покидає машину) і HTTP-хук на внутрішній сервіс аудиту. Для HTTP обов’язково обмежте URL та змінні середовища на рівні організації. Matcher містить . і *, тому обчислюється як regex, а не як список точних назв.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash|Edit|Write|mcp__.*",
      "hooks": [
        {
          "type": "command",
          "command": "jq -c '{ts: (now|todate), session: .session_id, tool: .tool_name, input: .tool_input}' >> ~/.claude/audit.jsonl",
          "async": true
        },
        {
          "type": "http",
          "url": "https://audit.company.com/claude",
          "headers": { "Authorization": "Bearer $AUDIT_TOKEN" },
          "allowedEnvVars": ["AUDIT_TOKEN"]
        }
      ]
    }]
  }
}

{
  "allowedHttpHookUrls": ["https://audit.company.com/*"],
  "httpHookAllowedEnvVars": ["AUDIT_TOKEN"]
}

6. Ворота перед git push: детермінований скрипт + LLM

Спершу дешева детермінована перевірка (force push і push у main/master блокуємо exit 2), далі — prompt-хук, який оцінює решту (наприклад, чи не лишилось налагоджувального коду). Обидва мають if, тож для інших Bash-команд процеси навіть не стартують. Усі хуки групи йдуть паралельно, а при розбіжності діє пріоритет deny.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "if": "Bash(git push *)",
          "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/push-guard.sh",
          "args": []
        },
        {
          "type": "prompt",
          "if": "Bash(git push *)",
          "prompt": "Ти рев’юер перед push у GitLab. Дані події: $ARGUMENTS. Відхили (ok:false з коротким reason), якщо команда пушить гілку, яка схожа на main/master/release, або явно містить налагоджувальні артефакти. Інакше ok:true.",
          "continueOnBlock": true,
          "timeout": 30
        }
      ]
    }]
  }
}

#!/bin/bash
cmd=$(jq -r '.tool_input.command')
if grep -Eq -- '--force( |$)|(^| )-f( |$)' <<<"$cmd"; then
  echo "Force push заборонено. Використайте --force-with-lease у feature-гілці" >&2; exit 2
fi
if grep -Eq '(^| |:)(main|master)( |$)' <<<"$cmd"; then
  echo "Push напряму в main/master заборонено - відкрийте Merge Request" >&2; exit 2
fi
exit 0

Повна довідка по хуках: усі події, обробники, matcher, коди завершення, JSON-вивід, змінні середовища, безпека й налагодження. Конфігурація й картки ключів — у попередньому розділі «hooks».

Події: сесія і середовище

Події: промпт і сповіщення

Події: інструменти і дозволи

Події: субагенти та задачі

Події: завершення і компактування

Події: моделі, worktree, MCP

Типи обробників

Є п’ять типів. Спільні поля:

Специфічні поля:

Які типи підтримує подія

Таймаути за замовчуванням

Фонові хуки: async і asyncRewake

Matcher: як рахується збіг

Matcher чутливий до регістру. Що саме він фільтрує — див. колонку «Matcher» в таблицях подій. Для подій без підтримки matcher (UserPromptSubmit, PostToolBatch, Stop, TeammateIdle, TaskCreated, TaskCompleted, WorktreeCreate, WorktreeRemove, MessageDisplay, CwdChanged) поле тихо ігнорується.

Поле if: фільтр за аргументами

if — рівно одне правило в синтаксисі дозволів, без &&, || і списків; для кількох умов робіть окремі обробники. Обчислюється лише на tool-подіях (див. вище). Для файлових інструментів Edit(src/**) збігається лише з <cwd>/src (з v2.1.214); каталог src на довільній глибині — Edit(**/src/**). Правила Edit(...) в системі дозволів охоплюють усі вбудовані інструменти редагування файлів.

Вхід (stdin / тіло POST)

Кожна подія додає до спільних полів свої (див. таблиці подій). Для command-хуків це JSON у stdin, для HTTP — тіло запиту. Моделі в спільних полях немає: змінної $CLAUDE_MODEL не існує, а поле model може прийти лише в SessionStart; для відстеження використовуйте PostModelSwitch.

Коди завершення

Що робить exit 2 на кожній події

JSON-вивід

Stdout повинен містити лише JSON-об’єкт. Універсальні поля приймає кожна подія (деякі їх відкидають):

Переписування та контекст

Для PreToolUse верхньорівневі decision/reason застарілі (approve/block відображаються на allow/deny). Рядки additionalContext, systemMessage, initialUserMessage і звичайний stdout обмежені 10 000 символами кожен, а надлишок іде у файл із прев’ю 2000 символів. Пишіть контекст як факти («цільове середовище — production»), а не як імперативні «системні» команди: так він сприймається як дані проєкту й не провокує захист від prompt injection.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Міграції правити не можна: створіть нову"
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": { "command": "pytest -x -q" }
  }
}

{ "decision": "block", "reason": "Запустіть pytest і виправте помилки" }

{ "continue": false, "stopReason": "Збірка впала, виправте помилки" }

Змінні середовища хуків

Хук успадковує середовище батьківського процесу, окрім змінних OTEL_* (і тих, що вилучає CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1). Плейсхолдери ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA} підставляються в command і args і водночас експортуються як змінні. У shell-form обгортайте їх у лапки; у exec form (args) лапки не потрібні. Змінних $CLAUDE_FILE_PATH і $CLAUDE_MODEL немає.

Хуки в skills, субагентах і плагінах

---
name: deploy-staging
description: Деплой на staging з перевіркою
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/deploy-guard.sh"
          args: []
          once: true
---
Деплой виконуй лише після зеленого pipeline.

Безпека

Налагодження

Що саме ізолює sandbox

Sandbox — межа на рівні ОС навколо shell-команд (Bash, PowerShell і Monitor) та їхніх дочірніх процесів. Вона вимкнена за замовчуванням: вмикається через /sandbox або sandbox.enabled. Побудований на відкритому пакеті @anthropic-ai/sandbox-runtime.

Платформи

Якщо sandbox не може стартувати (бракує залежності, непідтримувана платформа), Claude Code типово запускає команди без sandbox; щоб натомість завершувати запуск з помилкою — failIfUnavailable: true. У контейнері без привілеїв bubblewrap не змонтує /proc: див. enableWeakerNestedSandbox.

Режими sandbox і взаємодія з дозволами

Auto-allow у sandbox і режим auto (класифікатор) — різні речі; вони незалежні й комбінуються. Правила дозволів та sandbox доповнюють одне одного: шляхи з Edit-allow, Read/Edit-deny та домени з WebFetch(domain:) зливаються в підсумкову конфігурацію sandbox.

Мережа: що з хостами поза allowedDomains

Команда лишається в sandbox і чекає рішення; воно залежить від режиму дозволів:

З strictAllowlist або allowManagedDomainsOnly проксі відхиляє з’єднання в усіх режимах; deniedDomains — теж. «Yes» дозволяє хост до кінця сесії, «Yes, and don’t ask again» зберігає правило WebFetch(domain:…) у локальні налаштування.

• Інструменти без підтримки проксі (ssh, більшість драйверів БД, UDP, QUIC, ping) не підключаться навіть до дозволеного хоста — їх виносять в excludedCommands.
• Хости, що резолвляться в loopback/link-local (169.254.169.254), відхиляються; localhost дозволений. Корпоративний проксі задають через HTTPS_PROXY в env.
• IPv6 пишіть у дужках: "[::1]", "[::1]:443" (v2.1.229+). Запис без порту дозволяє всі порти хоста.
• Проксі вирішує за іменем хоста і за замовчуванням не розшифровує TLS, тож можливий domain fronting; не дозволяйте надто широкі домени на кшталт github.com, якщо важливий ризик витоку.

Вихід із sandbox (escape hatch)

Коли команда не працює в sandbox, Claude може повторити її з параметром dangerouslyDisableSandbox. Хто це схвалює — залежить від режиму:

• Збіжне allow-правило (наприклад Bash(curl *)) схвалює й повтор поза sandbox без запиту.
• Ask-правило Bash(dangerouslyDisableSandbox:true) змушує питати завжди (навіть в auto і bypass) і має пріоритет над allow.
• allowUnsandboxedCommands: false («strict sandbox mode») — параметр ігнорується, повтору немає. false з user/managed/--settings утримується навіть проти true з проєктного файлу (з v2.1.285).
• Команди, які ви вводите вручну через !, у більшості сесій ідуть поза sandbox.

"sandbox": {
  "enabled": true,
  "autoAllowBashIfSandboxed": true,   // default; false = regular permissions
  "allowUnsandboxedCommands": false,  // strict sandbox mode: ігнорувати dangerouslyDisableSandbox
  "failIfUnavailable": true           // не стартувати без sandbox
}

"filesystem": {
  "allowWrite": ["~/.cache/pip", "~/.npm"],   // робоча тека і так записувана
  "denyWrite": ["./config/prod.json"],
  "denyRead": ["~/.ssh", "~/.aws"]
}

"network": {
  "allowedDomains": ["*.github.com", "registry.npmjs.org", "pypi.org"],
  "deniedDomains": ["uploads.github.com"],
  "allowLocalBinding": true,             // localhost:8000 — ok (macOS)
  "allowUnixSockets": ["/var/run/docker.sock"]  // docker (macOS)
}

"excludedCommands": ["docker compose *", "python manage.py migrate *"]

"credentials": {
  "files":   [{ "path": "~/.aws/credentials", "mode": "deny" }],
  "envVars": [{ "name": "GITHUB_TOKEN", "mode": "deny" }]
}

"sandbox": {
  "enabled": true,
  "autoAllowBashIfSandboxed": false   // хочу бачити запити навіть у sandbox
}

"sandbox": {
  "enabled": true,
  "allowUnsandboxedCommands": false,
  "failIfUnavailable": true
}

"sandbox": { "enabled": true, "failIfUnavailable": true }

"sandbox": {
  "filesystem": {
    "denyRead": ["~/"],
    "allowRead": ["."]    // у project settings "." = корінь проєкту
  }
}

"sandbox": {
  "enabled": true,
  "filesystem": { "disabled": true },
  "network": { "allowedDomains": ["github.com", "*.npmjs.org"] }
}

"sandbox": {
  "filesystem": {
    "denyRead": ["~/"],
    "allowRead": ["~/work"],
    "allowManagedReadPathsOnly": true
  }
}

"sandbox": {
  "network": {
    "allowedDomains": ["pypi.org", "registry.npmjs.org"],
    "strictAllowlist": true
  }
}

"sandbox": {
  "network": {
    "allowManagedDomainsOnly": true,
    "allowedDomains": ["github.com", "*.npmjs.org", "pypi.org"]
  }
}

"sandbox": { "network": { "allowAllUnixSockets": true } }

"sandbox": { "network": { "allowMachLookup": ["com.apple.coresimulator.*"] } }

"sandbox": { "network": { "httpProxyPort": 8080 } }

"sandbox": { "network": { "socksProxyPort": 8081 } }

"sandbox": {
  "network": {
    "tlsTerminate": {}      // або { "caCertPath": "...", "caKeyPath": "..." }
  }
}

"sandbox": { "credentials": { "allowPlaintextInject": true } }

"sandbox": {
  "credentials": {
    "awsPairs": [
      { "accessKeyIdVar": "MY_KEY_ID", "secretAccessKeyVar": "MY_SECRET_KEY" }
    ]
  }
}

"sandbox": { "credentials": { "sigv4": { "streaming": "passthrough" } } }

"sandbox": {
  "ignoreViolations": {
    "*": ["/etc/hosts"],
    "npm": ["~/.npmrc"]
  }
}

"sandbox": { "enabled": true, "enableWeakerNestedSandbox": true }

"sandbox": { "enabled": true, "enableWeakerNetworkIsolation": true }

"sandbox": { "enabled": true, "allowAppleEvents": true }

"sandbox": {
  "ripgrep": { "command": "/usr/local/bin/rg", "args": ["--no-config"] }
}

"sandbox": { "enabled": true, "bwrapPath": "/opt/admin/bwrap" }

"sandbox": { "enabled": true, "socatPath": "/opt/admin/socat" }

Реальний приклад sandbox для Django + Vue

Проєктні налаштування для команди: Python і npm встановлюють пакети лише з реєстрів та внутрішнього GitLab, секрети домашньої теки закриті, dev-сервери (Django :8000, Vite :5173) працюють на macOS. Команди, що ходять у PostgreSQL (драйвер не користується проксі), виносимо в excludedCommands з ask-правилом.

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "allowUnsandboxedCommands": false,     // без 'dangerouslyDisableSandbox'
    "excludedCommands": [
      "docker compose *",                  // docker несумісний із sandbox
      "python manage.py migrate *"         // psycopg не бачить проксі
    ],
    "filesystem": {
      "allowWrite": ["~/.cache/pip", "~/.npm"],
      "denyWrite": ["./.env", "./.env.production"],
      "denyRead": ["~/.ssh", "~/.aws"]
    },
    "network": {
      "allowedDomains": [
        "pypi.org", "files.pythonhosted.org",
        "registry.npmjs.org", "*.npmjs.org",
        "github.com", "gitlab.example.com"
      ],
      "allowLocalBinding": true            // macOS: runserver і vite dev
    },
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [{ "name": "NPM_TOKEN", "mode": "deny" }]
    }
  },
  "permissions": {
    "ask": ["Bash(python manage.py migrate *)", "Bash(docker compose *)"]
  }
}

• Пакети pip/npm ставляться через проксі, тож pypi.org та registry.npmjs.org мають бути в allowedDomains; strictAllowlist (лише user/managed) зробить список жорстким.
• Виключена команда має повний доступ, а Claude може змінити скрипт у робочій теці й запустити його поза sandbox — тримайте шаблони вузькими (python manage.py migrate *, а не python *) і залишайте ask-правило.
• На Linux/WSL2 allowLocalBinding не діє: у кожної команди свій loopback; щоб дістатися сервера на хості (БД у контейнері), виносьте команду в excludedCommands.
• jest: watchman несумісний із sandbox — запускайте jest --no-watchman. Go-CLI (gh, terraform) на macOS можуть не пройти перевірку TLS — винесіть їх в excludedCommands (enableWeakerNetworkIsolation — лише для MITM-проксі з власним CA). git через SSH на macOS у sandbox не працює — переведіть remote на HTTPS.

MCP-сервер — це локальний процес або віддалений ендпоінт, який дає Claude додаткові інструменти, ресурси та промпти (GitLab, база даних, Sentry тощо). Нижче: де зберігається конфігурація, як додати сервер, як налаштувати авторизацію, як організація обмежує доступ і які ключі settings за це відповідають.

Області (scopes) та файли конфігурації

Пріоритет, коли один сервер визначено в кількох місцях: managedMcpServers > local > project > user > сервери плагінів > конектори claude.ai. Claude Code підключається один раз, використовуючи визначення з найвищого джерела; запис береться цілком, поля між областями не зливаються. Області дедуплікуються за іменем, плагіни та конектори — за ендпоінтом (той самий URL або команда). Якщо одне ім’я має різні ендпоінти в кількох областях, claude mcp list і /mcp покажуть попередження (OAuth-вхід зберігається окремо для кожного ендпоінта).

Файл має той самий формат, що й .mcp.json. Його не можна доставити через server-managed settings — лише як файл на диску (Jamf, Intune, GPO тощо). Не клади ключі й паролі в env такого файлу: його читає будь-який користувач машини; використовуй ${VAR}, OAuth або headersHelper.

Транспорти

Ім’я сервера в командах claude mcp — лише літери, цифри, - та _. Зарезервовані імена: workspace, claude-in-chrome, computer-use, Claude Preview, Claude Browser (сервер із таким іменем пропускається, claude mcp add відхиляє ім’я).

Команди claude mcp add та керування

# Віддалений HTTP-сервер (область за замовчуванням — local, лише для вас у цьому проєкті)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# Спільний для команди сервер: запис потрапляє у .mcp.json (комітиться в git)
# УВАГА: адреса GitLab MCP — плейсхолдер; точний шлях ендпоінта звір із документацією свого GitLab
claude mcp add-json --scope project gitlab \
  '{"type":"http","url":"https://gitlab.acme.example/api/v4/mcp","headers":{"Authorization":"Bearer ${GITLAB_TOKEN}"}}'

# Локальний stdio-сервер для PostgreSQL (--scope user = усі ваші проєкти). Після -- іде команда сервера
claude mcp add --transport stdio --scope user db \
  -- npx -y @bytebase/dbhub --dsn "postgresql://readonly:PASSWORD@db.acme.example:5432/analytics"

# Секрет у змінній середовища сервера (між --env і іменем має бути інша опція, напр. --transport)
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

# Керування
claude mcp list                         # статус: Connected / Needs authentication / Failed / Pending approval
claude mcp get sentry                   # деталі одного сервера
claude mcp remove sentry --scope local  # також видаляє OAuth-токени та реєстрацію клієнта
claude mcp login sentry [--no-browser]  # OAuth з терміналу
claude mcp logout sentry
claude mcp reset-project-choices        # скинути схвалення серверів з .mcp.json
claude mcp add-from-claude-desktop      # імпорт із Claude Desktop (macOS і WSL)
claude mcp serve                        # запустити сам Claude Code як stdio MCP-сервер

У сесії: /mcp — панель статусів, авторизація, вмикання/вимикання серверів, список інструментів. Промпти MCP-сервера з’являються як команди /server:prompt (MCP) (також працює /mcp__server__prompt).

Реалістичний .mcp.json: GitLab + PostgreSQL + Sentry

Файл комітиться в репозиторій. Секрети не пишемо у файл — тільки посилання ${VAR}, кожен розробник задає змінні у своєму середовищі. Шлях /api/v4/mcp для GitLab — плейсхолдер: точну адресу MCP-ендпоінта звір із документацією свого інстансу GitLab; хости acme.example і адреса БД — теж приклади.

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "${GITLAB_URL:-https://gitlab.acme.example}/api/v4/mcp",
      "headers": {
        "Authorization": "Bearer ${GITLAB_TOKEN}"
      }
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL_READONLY}"],
      "env": {
        "PGCONNECT_TIMEOUT": "10"
      },
      "timeout": 60000
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Для БД бери користувача лише з правом читання. Sentry без заголовків авторизується через OAuth: /mcp або claude mcp login sentry.

Підстановка змінних середовища у .mcp.json

• Синтаксис: ${VAR} та ${VAR:-значення за замовчуванням}.
• Підставляється в полях command, args, env, url, headers.
• Якщо змінна не задана й немає :-default, конфіг усе одно завантажується: Claude Code показує попередження у виводі claude mcp list і лишає текст ${VAR} як є.
• У claude mcp list, claude mcp get і деталях /mcp (v2.1.268+) посилання показуються за іменем, а не розкритим значенням.
• CLAUDE_PROJECT_DIR виставляється в оточенні сервера, а не Claude Code, тому в command/args поза плагінами пиши ${CLAUDE_PROJECT_DIR:-.}. У плагінах ${CLAUDE_PROJECT_DIR} підставляється напряму.

Поля запису сервера

Схвалення project-серверів та довіра до папки

• Сервери з .mcp.json в інтерактивній сесії потребують схвалення (діалог). Скинути вибір — claude mcp reset-project-choices.
• У claude -p, Agent SDK та cloud-сесіях діалогу немає, тому project-сервери завантажуються без запиту. Щоб тримати їх осторонь: disabledMcpjsonServers (працює в усіх режимах), --setting-sources без project, або --strict-mcp-config (тільки сервери з --mcp-config).
• Клонований репозиторій не може схвалити сам себе: enableAllProjectMcpServers/enabledMcpjsonServers
• з закоміченого .claude/settings.json ігноруються, доки ти не прийняв діалог довіри до папки (діє й для claude mcp list / get з v2.1.196). Схвалення з user settings, managed та --settings працюють і в недовіреній папці.
• /mcp-перемикачі «вимкнути сервер» пишуть per-project у ~/.claude.json списки disabledMcpServers (вимкнути звичайний сервер, плагінний, claude.ai-конектор) і enabledMcpServers (увімкнути вбудований сервер, вимкнений за замовчуванням, напр. computer-use). Це не ті самі ключі, що *Mcpjson*.

Авторизація віддалених серверів

• OAuth 2.0 для HTTP/SSE: відповідь 401/403 позначає сервер у /mcp як такий, що потребує входу. Увійти — /mcp або claude mcp login <name> [--no-browser]. Токени зберігаються безпечно й оновлюються автоматично; «Clear authentication» у /mcp відкликає доступ.
• Якщо ти сам задав заголовок Authorization (у headers чи через headersHelper) і сервер його відхилив, Claude Code повідомить про помилку з’єднання й не перейде на OAuth.
• --callback-port фіксує redirect URI http://localhost:PORT/callback (також змінна MCP_OAUTH_CALLBACK_PORT).
• Немає Dynamic Client Registration — передай --client-id і --client-secret (маскований запит або змінна MCP_CLIENT_SECRET). Секрет можна задати лише при додаванні сервера; зберігається в keychain (macOS) або credentials-файлі. Підтримується також CIMD.
• oauth.authServerMetadataUrl (лише https://) перекриває стандартне виявлення метаданих; oauth.scopes — рядок scope через пробіл, що фіксує потрібний набір (спосіб обмежити сервер підмножиною прав, схваленою службою безпеки).
• У claude -p сам OAuth пройти не можна: потрібен попередній вхід через /mcp чи claude mcp login.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.acme.example",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    },
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": { "scopes": "channels:read chat:write search:read" }
    }
  }
}

headersHelper — команда, яка друкує у stdout JSON-об’єкт рядкових заголовків. Запускається через shell, тайм-аут 10 с, на кожне підключення/перепідключення та після 401/403; результат не кешується. Динамічні заголовки перекривають статичні. Змінні середовища для скрипта: CLAUDE_CODE_MCP_SERVER_NAME, CLAUDE_CODE_MCP_SERVER_URL, CLAUDE_PLUGIN_ROOT (лише для серверів плагіна). Для серверів із project .mcp.json та плагінів змінні з «обліковими» іменами (TOKEN, SECRET, KEY, AUTH …) з оточення прибираються; для project/local-серверів скрипт виконується лише після діалогу довіри до папки.

Конектори claude.ai

• Якщо ти увійшов через підписку claude.ai, конектори з claude.ai/customize/connectors автоматично доступні в Claude Code й у /mcp.
• Вони не завантажуються, якщо активні ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN чи apiKeyHelper, сторонній провайдер (Bedrock, Vertex …) або токен із claude setup-token.
• Сервер, доданий у Claude Code, має пріоритет над конектором з тим самим URL. Вимкнути всі — disableClaudeAiConnectors або ENABLE_CLAUDEAI_MCP_SERVERS=false; поодинці — deniedMcpServers або перемикач у /mcp.
• Організація може задати для інструментів конектора режими ask (запит на кожен виклик, навіть в bypassPermissions; у dontAsk — відмова) та blocked (інструмент для Claude прихований).

Settings-ключі MCP

Ці ключі діють у файлах settings (settings.json); конфігурація самих серверів — у .mcp.json / ~/.claude.json / managed-mcp.json.

"allowedMcpServers": [
  { "serverName": "github" },
  { "serverName": "trello" },
  { "serverUrl": "https://*.company.com/*" },
  { "serverCommand": ["npx", "-y", "@company/mcp-server"] }
]

"deniedMcpServers": [
  { "serverName": "filesystem" },
  { "serverUrl": "https://untrusted-mcp.io/*" },
  { "serverName": "claude.ai Slack" }
]

"enabledMcpjsonServers": ["github", "trello"],
"disabledMcpjsonServers": ["filesystem"],
"enableAllProjectMcpServers": false
// false = не авто-схвалювати всі MCP з .mcp.json
// у недовіреній папці true діє з user, managed та --settings (не з project-файлу)

"allowManagedMcpServersOnly": true,
"allowedMcpServers": [
  { "serverUrl": "https://mcp.sentry.dev/*" },
  { "serverCommand": ["npx", "-y", "@bytebase/dbhub", "--dsn", "postgresql://readonly@db.acme.example:5432/analytics"] }
],
"managedMcpServers": {
  "gitlab": {
    "type": "http",
    "url": "https://gitlab.acme.example/api/v4/mcp"  // плейсхолдер — підстав свій ендпоінт
  }
}

"disableClaudeAiConnectors": true

"allowAllClaudeAiMcps": true

"allowClaudeInChromeWithManagedMcp": true

"projects": {
  "/Users/me/work/shop": {
    "disabledMcpServers": ["sentry", "claude.ai Slack"],
    "enabledMcpServers": ["computer-use"]
  }
}

Шаблони керування MCP в організації

Перевірка на керованій машині: claude mcp list показує лише сервери з managed-mcp.json (плюс managedMcpServers); claude mcp add --transport http test https://example.com/mcp має впасти з «enterprise MCP configuration is active …».

Ліміти виводу MCP та змінні середовища

Змінні можна задати в оболонці або в блоці env settings. Приклад: export MAX_MCP_OUTPUT_TOKENS=50000 перед запуском claude.

Tool search: відкладене завантаження інструментів

За замовчуванням визначення MCP-інструментів відкладаються: на старті в контекст потрапляють лише назви інструментів та інструкції серверів, повні схеми підтягуються за потреби (інструмент ToolSearch). Тому додавання серверів майже не з’їдає контекст. Потрібна модель з підтримкою tool_reference (Sonnet/Haiku/Opus 4.5 і новіші).

• Інструмент можна вимкнути політикою: permissions.deny: ["ToolSearch"].
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS тримає tool search вимкненим, і перекрити це змінною ENABLE_TOOL_SEARCH неможливо; організація може залишити його ввімкненим через managed settings (v2.1.227+).
• На сервер: "alwaysLoad": true — інструменти завжди в контексті (старт чекає на сервер до 5 с); "alwaysLoad": false — завжди відкладені, навіть якщо автор позначив інструмент _meta["anthropic/alwaysLoad"] (v2.1.287+). На рівні інструмента автор сервера може виставити _meta["anthropic/alwaysLoad"].

Імена інструментів та дозволи

• Інструмент: mcp__<server>__<tool>; для плагінного сервера — mcp__plugin_<plugin>_<server>__<tool>. Правила permissions приймають і mcp__server, і mcp__server__*.
• Правила з параметрами (дужки) для MCP-інструментів працюють лише через --disallowedTools; settings-файли пропускають такі правила.
• У matcher хуків потрібно .*: mcp__memory нічого не збігається, а mcp__memory__.* — так.
• Сервер може вимагати підтвердження кожного виклику: _meta["anthropic/requiresUserInteraction"]: true у tools/list — запит показується в будь-якому режимі (навіть bypassPermissions, а у dontAsk виклик відхиляється).
• Сервер може запитувати введення у користувача посеред задачі (elicitation): діалог у режимі форми або URL; автовідповідь — хук Elicitation.

Плагін — це тека з компонентами, які Claude Code вантажує разом: скіли, агенти, хуки, MCP- та LSP-сервери, теми, монітори. Плагіни поширюються через marketplace — каталог (marketplace.json) у git-репозиторії, за URL або в локальній теці. Нижче — будова плагіна та marketplace, ключі settings, команди CLI і готовий рецепт для команди.

Що може містити плагін та структура теки

deploy-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/
│       └── SKILL.md
├── agents/
│   └── reviewer.md
├── hooks/
│   └── hooks.json
├── bin/
│   └── deploy-tool
├── scripts/
│   └── format.sh
├── settings.json
├── .mcp.json
└── .lsp.json

plugin.json: приклад

{
  "name": "django-review",
  "displayName": "Django Review",
  "version": "1.2.0",
  "description": "Рев’ю Django-коду: міграції, ORM-запити, DRF-серіалізатори",
  "author": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "license": "MIT",
  "keywords": ["django", "review"],
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "${user_config.gitlab_url}/api/v4/mcp",
      "headers": { "Authorization": "Bearer ${user_config.gitlab_token}" }
    }
  },
  "userConfig": {
    "gitlab_url": {
      "type": "string",
      "title": "GitLab URL",
      "description": "Адреса інстансу GitLab",
      "default": "https://gitlab.acme.example"
    },
    "gitlab_token": {
      "type": "string",
      "title": "GitLab token",
      "description": "Personal access token з правом read_api",
      "sensitive": true,
      "required": true
    }
  }
}

Адреса ${user_config.gitlab_url}/api/v4/mcp — плейсхолдер для GitLab MCP-ендпоінта; підстав реальний шлях свого інстансу.

Перевірка: claude plugin validate ./django-review (з --strict попередження стають помилками — зручно для CI). Невідомий ключ верхнього рівня відкидається з попередженням; невідомий ключ усередині userConfig / channels / lspServers / monitors — помилка, і плагін не завантажується.

Поля plugin.json

Усі шляхи компонентів відносні до кореня плагіна, починаються з ./, не виходять за корінь (без ..) і мають існувати. Якщо ключ замінює стандартну теку, а тека існує, claude plugin list покаже попередження «Default … folder is ignored».

userConfig та змінні середовища плагіна

• Значення посилаються як ${user_config.KEY} (у конфігах MCP/LSP, exec-form хуках, змісті скілів і агентів — секретні там стають плейсхолдером) та як змінна CLAUDE_PLUGIN_OPTION_<KEY> у процесах хуків. Не дозволено в shell-form хуках, командах моніторів і headersHelper (там — помилка).
• Несекретні значення зберігаються в pluginConfigs (user/managed), секретні — у системному keychain (або ~/.claude/.credentials.json).
• ${CLAUDE_PLUGIN_ROOT} — абсолютний шлях встановленої версії плагіна (змінюється при оновленні, стан тут не зберігай).
• ${CLAUDE_PLUGIN_DATA} — ~/.claude/plugins/data/<id>/: зберігається між оновленнями (node_modules, кеші); видаляється при видаленні останньої інсталяції, якщо не --keep-data.
• ${CLAUDE_PROJECT_DIR} — корінь проєкту. Ці змінні не експортуються в команди, які Claude виконує через Bash-інструмент.

marketplace.json

Файл лежить у .claude-plugin/marketplace.json кореня каталогу; відносні шляхи плагінів рахуються від цього кореня (не від .claude-plugin/). Якщо файл лежить деінде, користувачі мають оголосити marketplace в extraKnownMarketplaces із path у джерелі.

{
  "name": "acme-plugins",
  "owner": { "name": "Acme Platform Team", "email": "platform@acme.example" },
  "description": "Плагіни команди Django + Vue",
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    {
      "name": "django-review",
      "source": "django-review",
      "description": "Рев’ю Django-коду",
      "version": "1.2.0",
      "category": "code-review",
      "tags": ["django", "python"]
    },
    {
      "name": "vue-tools",
      "source": {
        "source": "git-subdir",
        "url": "https://gitlab.acme.example/platform/claude-tools.git",
        "path": "plugins/vue-tools",
        "ref": "v0.4.0"
      }
    },
    {
      "name": "deploy-helper",
      "source": {
        "source": "url",
        "url": "https://gitlab.acme.example/platform/deploy-helper.git",
        "ref": "main"
      }
    }
  ]
}