Конфігурація MCP у Claude Code: .mcp.json, області видимості

2026-09-09 Оновлено: 2026-09-14

Claude Code читає MCP-сервери з двох файлів: .mcp.json у корені проєкту для серверів, спільних із командою, і ~/.claude.json для ваших власних локальних серверів і серверів рівня користувача. Обидва використовують той самий об'єкт mcpServers, де кожен запис називає type - http, sse, ws або stdio, і сервер, який не з'являється, майже завжди означає неправильний type, нерозгорнуту змінну середовища або вхід, який так і не завершився.

Формат .mcp.json

Файл проєкту з одним віддаленим сервером і одним локальним виглядає так:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Поле type обов'язкове щоразу, коли присутнє url. url без type повертається як помилка конфігурації (повідомлення радить додати "type": "http", або sse, або ws), що замінило старішу й значно менш корисну скаргу на відсутню command. Значення streamable-http приймається як псевдонім для http. Віддаленому серверу, якому потрібні статичні облікові дані, додають об'єкт headers; локальному - command, args і env. Необов'язковий timeout - це ліміт на один виклик інструмента в мілісекундах. Сервери WebSocket можна оголосити лише у файлі або через claude mcp add-json; прапорець --transport значення ws не приймає.

Команда claude mcp add із --scope project сама записує цей файл, тож ручне редагування потрібне лише для полів, які команда не розкриває, або коли ви хочете переглянути зміну в pull request.

Як тримати секрети поза файлом

Оскільки .mcp.json призначений для коміту, токени вписувати в нього не варто. Claude Code розгортає змінні середовища в command, args, env, url і headers: ${VAR} бере значення змінної, а ${VAR:-default} відкочується на типове значення, коли її не задано.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Згадана змінна, яка не задана і не має типового значення, не заважає серверу завантажитися; буквальний текст ${API_KEY} надсилається як є, а claude mcp list друкує попередження. Саме це попередження варто шукати першим, коли сервер підключається, але кожен виклик відхиляється як неавторизований.

Для сервера з підтримкою OAuth ховати взагалі нічого: залиште в записі лише type і url, і кожен користувач входить один раз через /mcp. Токен зберігається окремо для кожного користувача, поза репозиторієм, і видаляється командою claude mcp remove.

Підтвердження, пріоритет і керовані сервери

Коли Claude Code вперше бачить сервер у .mcp.json проєкту, інтерактивна сесія питає, чи використовувати його; неінтерактивні запуски (claude -p, Agent SDK, хмарні сесії) завантажують його без запитань. Рішення запам'ятовується для кожного проєкту; claude mcp reset-project-choices скидає його, щоб можна було підтвердити заново після зміни.

Коли те саме ім'я визначено в кількох місцях, порядок такий: локальна область, потім область проєкту, потім область користувача, потім сервери, які надають плагіни, потім коннектори з claude.ai. Використовується весь запис переможця цілком. Організації можуть нав'язати фіксований список серверів через керований файл конфігурації або налаштування managedMcpServers (Claude Code 2.1.259 і новіші); вони стоять вище за будь-яку область рівня користувача, а керований файл, що заявляє ексклюзивний контроль, змушує claude mcp add відмовити з повідомленням про те, що діє корпоративна конфігурація. Списки дозволів і заборон (allowedMcpServers, deniedMcpServers) також можуть обмежувати, які URL чи команди користувачі можуть додавати, і заборона завжди перемагає.

Як читати вивід статусу

claude mcp list повідомляє по кожному серверу один зі статусів: підключено, потрібна автентифікація, не вдалося підключитися, очікує підтвердження, відхилено через disabledMcpjsonServers, або вимкнено для цього проєкту. Варто знати кілька менш очевидних попереджень, які він друкує: приховані пробіли на початку чи в кінці значення (вставлений токен, що закінчився переносом рядка), те саме ім'я, яке вказує на різні кінцеві точки в двох областях, і жменька зарезервованих імен, які не можна використати для власних серверів. Сервери WebSocket у списку взагалі не показуються; перевіряйте їх через claude mcp get <name> або /mcp.

Часті збої та їх виправлення

Віддалений сервер показує "needs authentication" або відповідає 401 чи 403. Відкрийте /mcp, виберіть сервер і завершіть вхід у браузері, або виконайте claude mcp login <name>. Якщо сервер використовує статичний токен, перевірте значення заголовка і попередження про нерозгорнуті змінні.
Локальний сервер не підключається під час запуску. Виконайте його команду вручну в тій самій оболонці, щоб побачити справжню помилку; звичайні причини - відсутнє середовище виконання, пакет, який треба встановити, або обов'язкова змінна середовища. Сервери, що запускаються повільно, впираються в ліміт запуску, який підіймає MCP_TIMEOUT у мілісекундах, наприклад MCP_TIMEOUT=10000 claude.
Сервер підключається, але інструмент повертає обрізаний результат. Вивід інструмента за замовчуванням обмежений 25 000 токенів, із попередженням від 10 000; MAX_MCP_OUTPUT_TOKENS підіймає цю межу.
Інструменти ніби відсутні в розмові. Claude Code відкладає визначення інструментів до моменту, коли вони справді потрібні, щоб контекст лишався компактним, тож на початку завантажуються лише імена й інструкції сервера; асистент все одно знаходить їх, коли запит збігається. Встановіть "alwaysLoad": true у записі сервера, якщо хочете, щоб його повні визначення були присутні з першого ж ходу.
Віддалений сервер обривається посеред сесії. Claude Code повторює спробу для обірваного з'єднання до п'яти разів із зростаючими затримками і до трьох разів для невдалого першого HTTP-з'єднання, але не для помилок автентифікації і не для локальних серверів, тож збій автентифікації сам себе не виправить.

Перевірка конфігурації на живому сервісі

Найшвидший спосіб перевірити .mcp.json проєкту - сервер, чиї відповіді можна перевірити незалежно. Із закоміченим { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } і кожним розробником, який один раз увійшов через /mcp, запит на кшталт "запусти HTTP-перевірку нашого staging-URL з Європи та Азії" має повернутися з реальними кодами стану й часом відповіді з контрольних точок HostTracker, що або підтверджує коректне читання файлу, або звужує проблему до входу в систему. Супутній посібник, як додати MCP-сервер у Claude Code, докладніше розбирає шлях через командний рядок і області видимості.