MCP сервер у Claude Code: підключення та налагодження

Castel Studio, Ніцца · Опубліковано 14 жовтня 2026 р.

Правильно підключений MCP сервер дає Claude Code доступ до зовнішніх інструментів: трекерів задач, баз даних, дизайнерських програм чи власних API. MCP (Model Context Protocol) — це відкритий стандарт для таких підключень. Саме налаштування складається з однієї команди, але більшість проблем виникає згодом: сервер працює у вас, але не у команди, ключ випадково потрапляє до репозиторію або інструменти відображаються у списку, проте ніколи не викликаються.

Ця інструкція базується на офіційній документації MCP для Claude Code. Ми щодня підключаємо MCP-сервери до Claude Code у власній студії, тож описані нижче помилки найчастіше трапляються в проєктах наших клієнтів.

Перед додаванням сервера: три запитання

Кому це потрібно? Тільки вам, усім учасникам цього проєкту чи вам у кожному проєкті. Відповідь визначає область (scope) і місце збереження конфігурації.
До чого він матиме доступ? Сервер, який лише читає дані з трекера, несе інші ризики, аніж той, що може змінювати базу даних чи надсилати листи. Починайте з режиму лише для читання, якщо сервіс це дозволяє.
Де зберігатимуться ключі? Вирішіть це до виконання першої команди. Токен, вписаний у спільний файл, — це помилка, яку найважче виправити, оскільки вона залишається в історії репозиторію.

Три способи додати сервер

Віддалений сервер через HTTP — типовий вибір для хмарних сервісів:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Якщо сервіс вимагає токен, передайте його через заголовок:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Локальний сервер через stdio запускається як програма на вашому комп’ютері:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Подвійний дефіс (--) тут важливий. Усе, що перед ним, призначено для Claude Code; усе, що після, є власною командою сервера та передається без змін.

Протокол SSE досі працює, але вважається застарілим. Надавайте перевагу HTTP, якщо сервіс його підтримує.

Області (scopes): хто бачить сервер

Кожен сервер додається з певною областю, і саме тут найчастіше виникають помилки у командній роботі.

Область	Де застосовується	Спільна з командою	Де зберігається
local (за замовчуванням)	цей проєкт, тільки ви	ні	`~/.claude.json`
project	цей проєкт	так, через репозиторій	`.mcp.json` у корені проєкту
user	усі ваші проєкти	ні	`~/.claude.json`

Виберіть область за допомогою прапорця --scope:

claude mcp add --transport http shared-server --scope project https://example.com/mcp

Якщо сервер з однаковою назвою існує в кількох областях, пріоритет має local, далі project, а потім user. Переможець використовується повністю; поля з різних областей не об’єднуються.

Командний файл .mcp.json без секретів

Область project створює файл, який можна комітити до репозиторію. Зберігайте ключі в безпеці за допомогою змінних середовища:

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

Конструкція ${VAR} замінюється значенням змінної, а ${VAR:-default} використовує резервне значення. Якщо змінна не має ні значення, ні дефолту, Claude Code виводить попередження та залишає текст без змін, завдяки чому відсутній ключ спричиняє помилку підключення, а не залишається непоміченим.

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

Перевірка роботи MCP-сервера

claude mcp list
claude mcp get notion

Команда claude mcp list показує статус кожного сервера: підключено, потрібна автентифікація або помилка з’єднання. Всередині сесії команда /mcp відображає те саме і дозволяє увійти до віддалених серверів через OAuth. Щоб видалити сервер, використовуйте claude mcp remove notion.

Найчастіші проблеми

Сервер працює лише у вас. Його додали з локальною областю за замовчуванням. Додайте його повторно з --scope project.
Ключ потрапив до репозиторію. Хтось випадково вставив токен у .mcp.json. Змініть ключ і перейдіть на використання ${API_KEY}.
Інструменти є у списку, але не викликаються. Правила доступу та шаблони хуків використовують повні назви інструментів: mcp__server__tool. Шаблон на кшталт mcp__memory нічого не знайде; детальніше дивіться у нашій статті про хуки Claude Code.
Завеликі відповіді. Claude Code попереджає, коли результат роботи одного інструменту перевищує 10 000 токенів, і обмежує його до 25 000 за замовчуванням (ліміт можна змінити через MAX_MCP_OUTPUT_TOKENS). Інструмент, який щоразу повертає всю таблицю, потребує фільтрів, а не більшого ліміту.
Неперевірений сервер. Сервери, які завантажують зовнішній контент, можуть переносити ін’єкції промптів у вашу сесію. Підключайте лише ті сервери, яким довіряєте, і давайте їм тільки той доступ, який дійсно потрібен для завдання.

Якщо ви вирішуєте, де саме має виконуватися завдання — у MCP-сервері, навивці чи субагенті, ознайомтеся з нашим посібником про агентів та навивки.

Коли варто звернутися по допомогу

Якщо вашій команді потрібно підключити Claude Code до власних систем — зі спільною конфігурацією, без секретів у репозиторії та надійними правилами, — ми налаштуємо MCP-сервери, агенти та перевірені правила і залишимо повністю робоче середовище. Ви можете переглянути, як влаштована наша власна система, на сторінці роботи.

Запитання

Чому мої колеги не бачать доданий мною MCP-сервер?

Тому що за замовчуванням область є локальною: сервер зберігається лише у вашому ~/.claude.json для цього проєкту. Додайте його з прапорцем --scope project, щоб записати у .mcp.json у репозиторії, який команда зможе за комітити.

Де зберігати API-ключі для MCP-сервера?

Не в самому .mcp.json. Використовуйте ${API_KEY} у полях url, headers, command, args чи env, а значення тримайте в змінній середовища. Конструкція ${VAR:-default} задає резервне значення.

Чому сервер у списку є, але Claude ніколи не використовує його інструменти?

Спочатку перевірте його статус через claude mcp list: можливо, потрібна автентифікація або сталася помилка підключення. Потім перевірте назви інструментів у правилах доступу й хуках — вони використовують формат mcp__server__tool.

Чи підтримується SSE досі?

Це працює, але є застарілим. Використовуйте HTTP-транспорт, де це можливо; новіші версії спочатку намагаються використати HTTP і самі перемикаються на SSE у разі потреби.