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

Коротко (TL;DR)

MCP-сервер дає Claude Code доступ до зовнішнього сервісу або даних — бази Postgres, репозиторіїв на GitHub, завдань у Jira, дизайну у Figma, пошуку в мережі. Підключається однією командою claude mcp add, працює через один із трьох транспортів (stdio, http, sse) і живе на одному з трьох рівнів видимості (local, project, user).

Важливе, про що майже не пишуть у гайдах: MCP не безкоштовний за контекстом. Одне визначення інструмента коштує приблизно 500–2000 токенів, а насичений сервер на кшталт GitHub — до 26 000 токенів на самі лише описи своїх інструментів (дані Anthropic на 24 листопада 2025). П’ять таких серверів — і модель витрачає 55 000+ токенів ще до того, як прочитає ваш запит. Саме цю проблему розв’язує Tool Search: він відкладає завантаження описів і підтягує потрібний інструмент на вимогу, скорочуючи витрату з ~77 000 до ~8,7 тис. токенів — мінус 85%. Із січня 2026 він увімкнений у Claude Code за замовчуванням.

І головне питання, яке варто поставити до встановлення будь-якого сервера: а чи потрібен тут узагалі MCP? Часто дешевше за токенами й надійніше звичайна Bash-команда або Skill. Нижче — команди покроково, таблиця рішення «MCP vs CLI vs Skill» і чесний розбір ризиків, зокрема архітектурна вразливість STDIO, про яку Anthropic заявила, що змінювати її не буде.

Дані перевірені за офіційною документацією Claude Code та інженерними матеріалами Anthropic на 11 липня 2026 року. Найзмінніше тут — номери версій CLI і точні цифри економії токенів: звіряйте їх у code.claude.com/docs/en/mcp перед налаштуванням продакшену.

Що таке MCP у контексті Claude Code

MCP (Model Context Protocol) — це відкритий стандарт, за яким ІІ-агент підключається до зовнішніх джерел даних та інструментів. Anthropic відкрила його 25 листопада 2024 року; автори протоколу — David Soria Parra та Justin Spahr-Summers. Ідея проста: замість того щоб під кожен сервіс писати окрему інтеграцію, ви піднімаєте «сервер», який говорить спільною мовою, — і будь-який MCP-клієнт (Claude Code, Claude Desktop, Cursor і десятки інших) вміє з ним працювати.

Хуки Claude Code: як автоматизувати дії агента і не підірватися на власних налаштуваннях

Плагіни в Claude Code: як встановити, створити власний маркетплейс і не спіймати шкідливий

SKILL.md без магії: збираємо власну навичку Claude Code за інженерними патернами

Agent Skills у Claude Code: як працюють, де взяти і як не поставити шкідливий скіл

Пам’ять Claude Code: Auto Memory, /memory і чому агент забуває

За рік протокол став одним із найшвидше зростаючих опенсорс-проєктів у сфері ІІ: понад 97 млн завантажень SDK на місяць і 10 000 активних серверів на 9 грудня 2025 року (дані офіційного блогу MCP). Тоді ж Anthropic передала керування протоколом до Agentic AI Foundation — фонду під егідою Linux Foundation, співзасновниками якого стали Anthropic, Block та OpenAI за підтримки Google, Microsoft, AWS, Cloudflare і Bloomberg. Тобто MCP перестав бути «фічею одного вендора» і став галузевим стандартом.

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

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

Три транспорти: як сервер спілкується з Claude Code

Транспорт — це спосіб, яким Claude Code обмінюється повідомленнями із сервером. Специфікація MCP визначає два стандартні механізми — stdio і Streamable HTTP; старий транспорт HTTP+SSE (версія протоколу 2024-11-05) оголошений застарілим і замінений на Streamable HTTP. Claude Code при цьому на рівні CLI підтримує додавання серверів за трьома транспортами плюс WebSocket через окрему команду.

Практичне правило: для локального інструмента беріть stdio, для хмарного — http; sse — лише якщо сервер не вміє інакше. Нові сервери піднімайте на HTTP.

Як підключити MCP-сервер: покроково

Розберемо три способи додати сервер — через claude mcp add, через файл .mcp.json і через вибір рівня видимості. Далі — автентифікація для віддалених серверів.

Крок 1. Команда claude mcp add під кожен транспорт

Базовий синтаксис однаковий для всіх транспортів, змінюється прапорець --transport і те, що йде після імені:

# Локальний stdio-сервер (транспорт за замовчуванням)
claude mcp add my-server -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# Віддалений HTTP-сервер
claude mcp add --transport http linear https://mcp.linear.app/mcp

# Віддалений SSE-сервер (застарілий транспорт)
claude mcp add --transport sse legacy-server https://example.com/sse

Подвійне тире -- перед командою stdio-сервера обов’язкове: усе, що після нього, Claude Code запускає як окремий процес. Після додавання перевірте статус командою claude mcp list (покаже connected або помилку) і claude mcp get <name> для деталей.

Є зарезервовані імена, які не можна займати своїми серверами: workspace, claude-in-chrome, computer-use, Claude Preview і Claude Browser зайняті вбудованими серверами Claude Code — конфіг із таким іменем просто пропускається під час завантаження.

Крок 2. Виберіть scope (рівень видимості)

Scope визначає, де зберігається конфіг сервера і хто його бачить. Це тонке місце, де найчастіше плутаються.

Задається прапорцем -s (або --scope):

claude mcp add -s project github-server -- npx -y @modelcontextprotocol/server-github
claude mcp add -s user my-notes -- npx -y some-personal-server

Логіка вибору: local — особистий чернетковий варіант під конкретний проєкт; project — спільний для команди сервер, який комітиться в репозиторій (.mcp.json), щоб в усіх було однакове середовище; user — особистий інструмент, потрібний в усіх проєктах одразу (наприклад, MCP-сервер пошуку або ваша персональна база знань).

Якщо той самий сервер задано на кількох рівнях, Claude Code підключається до нього один раз, беручи визначення з найпріоритетнішого рівня. Порядок пріоритету: local → project → user → сервери з плагінів → конектори claude.ai.

Крок 3. Файл .mcp.json і змінні оточення

Project-scope пише конфіг у .mcp.json у корені репозиторію. Його можна правити руками — зручно для команди і для секретів, які не можна хардкодити. MCP підтримує підстановку змінних оточення:

• ${VAR} — підставляє значення змінної VAR;
• ${VAR:-default} — значення VAR, а якщо її не задано — дефолт.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_HOST": "${GITHUB_HOST:-github.com}"
      }
    }
  }
}

Так токен не потрапляє в git, а кожен розробник підставляє свій з оточення. Окрема тонкість, на якій спотикаються навіть досвідчені: .mcp.json (project-scope) і ~/.claude.json (local/user-scope) — це не те саме, що .claude/settings.local.json. Останній — загальні налаштування Claude Code, а не місце для MCP-серверів. Шукаєте сервер не там — не знайдете.

Крок 4. Автентифікація віддалених серверів (OAuth 2.0)

Хмарні сервери зазвичай вимагають входу. Claude Code позначає віддалений сервер як «потрібна автентифікація», коли той відповідає 401 Unauthorized або 403 Forbidden. Далі:

• увійти інтерактивно — команда /mcp усередині сесії;
• увійти з шелла — claude mcp login <name> (доступно з версії v2.1.186), запускає OAuth-флоу сервера прямо з термінала.

Важливо: OAuth працює лише для транспортів http і sse. Для stdio-серверів ці прапорці не мають ефекту — локальний процес автентифікується власними засобами (наприклад, токеном у змінній оточення).

Tool Search: навіщо він і що дає в цифрах

Ось проблема, заради якої все це існує. Кожен MCP-сервер вставляє описи своїх інструментів прямо в контекст моделі. За даними інженерного блогу Anthropic (24 листопада 2025), типова п’ятисерверна зв’язка виглядає так: GitHub — 35 інструментів (~26 тис. токенів), плюс Slack, Jira та інше — загалом 58 інструментів і близько 55 тис. токенів ще до того, як почалася розмова. Усередині Anthropic бачили роздування до 134 тис. токенів лише на визначеннях. Це не абстракція: що більше контексту зайнято описами, то менше залишається під роботу і то сильніше падає точність моделі.

Tool Search перевертає схему: описи інструментів не завантажуються заздалегідь, а виявляються на вимогу. Модель спершу шукає потрібний інструмент за коротким індексом і підвантажує повне визначення лише того, що реально збирається викликати.

Цифри з внутрішніх тестів Anthropic (на 24 листопада 2025):

Зверніть увагу: економія токенів не просто «здешевлює» роботу — вона піднімає точність, бо модель не тоне в тисячах описів, які їй зараз не потрібні. Це рідкісний випадок, коли оптимізація за вартістю та за якістю йдуть в один бік.

Окремо про абсолютні числа: VentureBeat із посиланням на розбір у спільноті наводить іншу пару — 134 тис. → 5 тис. токенів. Розбіжність із офіційними 77 тис. → 8,7 тис. пояснюється різним набором серверів у тесті; підсумковий відсоток скорочення (85%) збігається в обох випадках.

У Claude Code Tool Search став публічно доступним 14–15 січня 2026 року — це була одна з найзапитуваніших спільнотою фіч (GitHub-запит на «розумне представлення інструментів» набрав десятки апвоутів задовго до релізу). Керування — через змінну ENABLE_TOOL_SEARCH (true/false/auto/auto:N). Одне обмеження: функція вимагає модель із підтримкою блоків tool_reference — моделі Haiku її не підтримують. Якщо якийсь інструмент потрібен завжди і його не має «шукати» агент, для нього можна задати alwaysLoad — тоді він завантажується одразу, в обхід відкладеного пошуку.

Коли MCP потрібен, а коли краще CLI чи Skill

Це розділ, який відрізняє практика від євангеліста. MCP — не єдиний спосіб дати Claude Code нову можливість, і часто не найкращий. Є три інструменти з різною ціною та призначенням.

Офіційне розмежування Anthropic звучить так: «MCP підключає Claude до зовнішніх сервісів. Skills розширюють те, що Claude знає, — зокрема те, як цими сервісами ефективно користуватися. Це різні завдання, і вони добре працюють разом». Простіше: MCP дає доступ, Skill дає знання, звичайна CLI-команда дає разову дію.

Ціна питання в токенах (порядок величини, оцінка стороннього аналізу — не офіційна метрика Anthropic, але масштаб збігається з цифрами по 50+ інструментах): одне визначення MCP-інструмента — ~500–2000 токенів у контексті; еквівалентний Skill — ~200 токенів під час завантаження і нуль, коли не використовується. Bash-команда не коштує нічого, доки ви її не викликали.

Дерево рішення:

Практичний тест: якщо завдання закриває curl або наявний CLI-клієнт, а викликати його треба зрідка — не піднімайте MCP-сервер, ви просто додасте 26 тис. токенів постійного оверхеду заради того, що розв’язується однією командою. MCP виправданий, коли сервіс потрібен часто, операцій багато, і ви хочете, щоб агент сам обирав потрібну зі структурованого набору — наприклад, Slack як MCP-сервер для постійної роботи з повідомленнями або сервер до вашої персональної бази знань.

Де ламається: типові помилки

У євангелістів усе завжди працює. У реальності MCP-сервери відвалюються з передбачуваних причин.

Окремо про перепідключення: HTTP і SSE-сервери Claude Code відновлює автоматично з експоненційною затримкою, а stdio — локальні процеси — самі не піднімаються. Якщо локальний сервер упав, його потрібно перезапустити.

Ризики та безпека: кому ви довіряєте виконання

Це YMYL-частина, і тут ми не згладжуємо. MCP-сервер — це код, який виконується на вашій машині з вашими правами. Точна й чесна рамка: сервер може робити те саме, що можете ви — читати ваші файли, ходити в мережу, смикати API від вашого імені. Звідси три реальні ризики.

1. Архітектурна вразливість STDIO (supply chain). 15 квітня 2026 року OX Security опублікувала розбір системної вразливості в транспорті STDIO: можливість ін’єкції команд і віддаленого виконання коду (RCE). Це не баг одного сервера, а поведінка, закладена в усіх офіційних SDK (Python, TypeScript, Java, Rust). Масштаб ланцюга постачання: 150 млн+ завантажень, 7000+ публічно доступних серверів, до 200 000 потенційно вразливих інстансів, 10+ випущених CVE. Anthropic підтвердила поведінку як «дизайн-рішення» і «безпечний дефолт», відмовившись міняти протокол: санітизація вводу — відповідальність розробника конкретного сервера.

Що це означає для вас без паніки: ризик здебільшого стосується серверів, які самі передають неперевірений користувацький ввід в аргументи команд, а не будь-якого stdio-сервера за замовчуванням. Практичний висновок — ставте stdio-сервери лише з джерел, яким довіряєте, і не запускайте випадкові пакети з незрозумілою репутацією.

2. Tool poisoning (отруєння інструментів). На початку 2026 року Snyk Security Labs задокументувала атаку, де шкідливий опис MCP-інструмента змушував агента вивантажувати дані репозиторію GitHub на сервер зловмисника — без додаткових дій користувача. Вектор — поле description інструмента: агент читає його як інструкцію і виконує. Урок: опис інструмента — це теж вхідні дані, і недовірений сервер може вписати туди будь-що.

3. Prompt injection через контент. Сервери, які тягнуть зовнішній контент (документацію, вебсторінки, тикети), можуть принести в контекст моделі приховану інструкцію. Цей загальний ризик незалежно відзначають технічні розбори (наприклад, dou.ua): якщо MCP-сервер забирає неперевірений текст, у ньому може бути вбудована команда агенту.

Окремо варто тримати в голові масштаб екосистеми як фактор ризику. Оцінки числа серверів розходяться: 10 000 за офіційним реєстром (грудень 2025) проти ~7000 «у дикій природі» за сканом OX Security (початок 2026). Це не помилка, а різні методики підрахунку — але сам розкид показує, наскільки великий і слабко контрольований ланцюг постачання. Практика безпеки: мінімум одночасно активних серверів, project-scope з явною довірою, жодних секретів у .mcp.json безпосередньо (тільки через ${VAR}), і здорова параноя до незнайомих пакетів.

Просунутий прийом: code execution замість прямих викликів

Якщо Tool Search економить контекст на описах, то наступний рівень — економія на результатах. Anthropic описала підхід (4 листопада 2025), за якого модель не викликає MCP-інструменти безпосередньо, а пише код на TypeScript або Python, який сам смикає ці інструменти в ізольованому середовищі. Проміжні результати не завалюють контекст: модель отримує лише фінальну відповідь. На власному прикладі Anthropic це дало економію до 98,7% (зі 150 000 до 2 000 токенів); Cloudflare незалежно описала той самий підхід, назвавши його Code Mode. Прийом не для кожного завдання, але там, де агент робить багато послідовних викликів з великими виходами, він радикально змінює вартість роботи.

FAQ

Чим MCP у Claude Code відрізняється від конекторів у claude.ai? Це різні поверхні продукту. Конектори в claude.ai і Claude Desktop — споживчий інтерфейс: ви обираєте сервіс (Gmail, Calendar, Notion) з каталогу і даєте права кліками. MCP у Claude Code — розробницький рівень: ви самі піднімаєте сервери командою claude mcp add, керуєте транспортами, scope і .mcp.json. Під капотом протокол один, але керування й гнучкість різні.

Чи потрібно вмикати Tool Search вручну? Ні. У Claude Code він увімкнений за замовчуванням із середини січня 2026 року — опт-ін не потрібен. Керувати поведінкою можна змінною ENABLE_TOOL_SEARCH. Єдине обмеження — модель має підтримувати блоки tool_reference; моделі Haiku їх не підтримують, там Tool Search не працює.

Чому мій project-сервер висить у статусі Pending approval? З версії v2.1.196 сервер, заданий у .mcp.json, не запускається в недовіреному репозиторії, доки ви явно не довірите workspace. Це захист від того, щоб клонований чужий репозиторій не підняв довільний сервер у вас на машині. Підтвердьте довіру до проєкту — сервер запуститься.

Скільки MCP-серверів можна тримати ввімкненими одночасно? Технічно обмеження немає, але кожен сервер займає контекст під описи інструментів (насичений — десятки тисяч токенів). До Tool Search це була пряма проблема; зараз відкладене завантаження знімає основне навантаження. Усе одно правило безпеки та гігієни контексту — тримати активними лише реально потрібні сервери, а не «про всяк випадок».

Чи можна обійтися без MCP взагалі? Часто так. Якщо завдання — разова або скриптована дія, звичайна Bash/CLI-команда дешевша й надійніша (нуль токенів на визначення). Якщо треба навчити агента процесу або стандарту — це Skill. MCP виправданий, коли потрібен постійний структурований доступ до зовнішнього сервісу з багатьма операціями.

Чи безпечно підключати сторонні MCP-сервери? Із застереженнями. Сервер виконується з вашими правами і може те саме, що й ви. Ризики реальні: архітектурна вразливість STDIO (OX Security, квітень 2026), отруєння описів інструментів (Snyk), prompt injection через принесений контент. Ставте сервери лише з джерел, яким довіряєте, не зберігайте секрети відкритим текстом у .mcp.json і тримайте мінімум активних серверів.