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

Claude Code «з коробки» вже вміє читати локальні файли, виконувати команди в терміналі та редагувати вихідний код проєкту. Проте у реальних завданнях розробки цього часто недостатньо: виникає потреба отримати інформацію з бази даних PostgreSQL, перевірити відкриті Pull Requests на GitHub, підтягнути актуальну документацію з хмари чи надіслати запит до внутрішнього корпоративного API.

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

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

1. Що таке MCP Server

Model Context Protocol (MCP) — відкритий протокол комунікації, розроблений компанією Anthropic, що стандартизує взаємодію між мовними моделями (LLM) та зовнішніми інструментами чи джерелами даних.

Замість написання окремих унікальних плагінів під кожен сервіс, MCP запроваджує єдиний клієнт-серверний інтерфейс.

Будь-який MCP Server надає моделі три базові примітиви:

• Tools (Інструменти) — виконувані функції з типізованою JSON-схемою параметрів, які Claude Code може самостійно викликати під час розв'язання задачі (наприклад, create_issue, execute_query).
• Resources (Ресурси) — пасивні дані або схеми, які асистент може зчитувати як вхідний контекст (файли, схеми БД, лоґи).
• Prompts (Шаблони промптів) — готові контекстні сценарії, які спрощують виконання типових повторюваних завдань.

Порівняння можливостей Claude Code

2. Архітектура та принцип роботи MCP

Архітектура взаємодії базується на стандартному протоколі JSON-RPC 2.0. У більшості локальних сценаріїв комунікація відбувається через стандартні потоки введення/виведення (stdio), а для віддалених серверів — через Server-Sent Events (SSE) або HTTP.

Покроковий життєвий цикл запиту

1. Ініціалізація та Handshake: При запуску сесії Claude Code зчитує конфігураційний файл, запускає зазначені процеси серверів і запитує список підтримуваних інструментів (tools/list).
2. Публікація можливостей: Кожен MCP Server повертає список своїх методів разом із JSON-схемами параметрів та детальним описом призначення.
3. Оцінка наміру: Коли ви ставите завдання природною мовою, Claude співставляє ваш запит із доступними інструментами.
4. Виклик інструмента: Якщо завдання вимагає зовнішніх даних, модель надсилає структурований запит tools/call серверу з валідними аргументами.
5. Виконання на боці сервера: Сервер зв'язується із зовнішнім API, базою даних чи диском і повертає результат клієнту.
6. Генерація відповіді: Отримавши сирі дані, Claude інтерпретує їх та надає вам фінальну структуровану відповідь.

3. Як підключити MCP Server до Claude Code

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

1. Конфігурація проєкту (.claude/settings.json) — застосовується виключно до поточної директорії та може бути збережена у репозиторії для всієї команди.
2. Глобальна конфігурація (~/.claude/settings.json) — доступна для всіх проєктів поточного користувача на комп'ютері.

json
Копіювати
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem",
        "./docs"
      ]
    }
  }
}

Структура параметрів конфігурації

Кожен запис сервера у секції mcpServers складається з трьох ключових полів:

4. Каталог готових MCP Servers

Anthropic та відкрита спільнота розробили готові сервери для найпопулярніших інструментів. Вам не потрібно писати код з нуля — достатньо підключити відповідний npm- або python-пакет.

1. Filesystem Server

Надає Claude Code доступ до директорій за межами поточного репозиторію (наприклад, до глобальної папки з документацією або нотатками Obsidian).

2. GitHub Server

Дозволяє асистенту напряму працювати з репозиторіями організації: читати issues, залишати коментарі до PR і перевіряти статус пайплайнів.

3. PostgreSQL Server

Дає можливість Claude виконувати аналітичні або діагностичні запити безпосередньо до вашої локальної чи віддаленої бази даних.

4. Brave Search Server

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

5. Як Claude Code використовує MCP у діалозі

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

Приклад сценарію: робота з GitHub

Запит користувача:

"Перевір, які відкриті issues призначені на мене в репозиторії acme/platform, і виведи короткий список найпріоритетніших."

Внутрішній процес Claude Code:

1. Модель розпізнає, що локальних файлів недостатньо для відповіді.
2. Вона формує виклик mcp__github__search_issues з фільтрами repo:acme/platform state:open assignee:@me.
3. Отримує структуровану JSON-відповідь від сервера GitHub.
4. Форматує відповідь у зручний вигляд.

6. Створення власного MCP Server на TypeScript

Якщо готових рішень недостатньо і вам потрібен специфічний інструмент під бізнес-логіку або внутрішні мікросервіси, MCP Server можна написати самостійно за лічені хвилини за допомогою офіційного SDK @modelcontextprotocol/sdk.

Крок 1. Ініціалізація та встановлення залежностей

Створіть окрему директорію та встановіть бібліотеки:

Крок 2. Реалізація сервера (server.ts)

Створіть файл server.ts із визначенням сервера та кастомного інструмента:

Крок 3. Підключення сервера до Claude Code

Додайте створений сервер у .claude/settings.json вашого проєкту:

7. Безпека та ізоляція при роботі з MCP

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

1. Сервер виконується з вашими системними правами

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

2. Захист секретів та ключів API

Ніколи не зберігайте бойові ключі у репозиторії. Використовуйте глобальну конфігурацію ~/.claude/settings.json для чутливих токенів або передавайте змінні оточення через .env-файли, внесені до .gitignore.

3. Перевірка сторонніх пакетів перед підключенням

Завжди аудитуйте репозиторій або npm-пакет стороннього MCP Server перед додаванням у конфігурацію:

• Переконайтеся у наявності відкритого вихідного коду.
• Перевірте кількість завантажень та активність репозиторію.
• Звертайте увагу на мережеві запити, які виконує сервер під час старту.

4. Розділення рівнів конфігурації

8. Практичний воркшоп: покрокове налаштування

Виконайте два практичні завдання для закріплення матеріалу та перевірки коректності підключення серверів.

Завдання 1. Підключення GitHub MCP Server

1. Створіть новий Personal Access Token (classic або fine-grained) на GitHub у розділі Settings → Developer settings із дозволами repo та read:org.
2. Відкрийте або створіть конфігураційний файл ~/.claude/settings.json:

3. Запустіть нову сесію Claude Code та виконайте верифікаційний промпт:

Промпт для тестування:
"Покажи мої 5 останніх оновлених репозиторіїв на GitHub та їхній статус."

• Claude Code успішно викликав інструмент GitHub без помилок автентифікації.
• Отримано актуальний перелік репозиторіїв.

Завдання 2. Підключення Filesystem Server для зовнішніх нотаток

Надайте Claude доступ до зовнішньої папки з документацією або архітектурними нотатками:

1. Додайте сервер filesystem у .claude/settings.json:

2. Перевірте роботу запитом до Claude:

Промпт для тестування:
"Знайди в папці external-docs усі markdown-файли, що описують архітектуру API, та склади їхній короткий огляд."

• Claude зчитав файли за межами робочої директорії проєкту.
• Узагальнив знайдену інформацію без втрати контексту.

9. Швидка самоперевірка знань

Перевірте, наскільки добре ви засвоїли фундаментальні принципи архітектури Model Context Protocol.

Питання 1. Що є базовим призначенням MCP Server?

• A. Хмарна віртуальна машина для хостингу моделей Claude
• B. Програма-адаптер, яка надає мовній моделі стандартизований доступ до зовнішніх інструментів та даних
• C. Бібліотека для автоматичного стиснення векторних ембеддінгів
• D. Веб-сервер для публікації скомпільованого коду проєкту

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

• A. ~/.claude/settings.json
• B. package.json
• C. .claude/settings.json у корені проєкту
• D. CLAUDE.md

Питання 3. Як Claude Code дізнається, який інструмент використати для відповіді на запитання?

• A. Користувач зобов'язаний явно вказувати прапорець --tool=name перед кожним запитом
• B. Потрібно попередньо викликати команду /mcp select
• C. Модель аналізує семантику запиту та описи JSON-схем інструментів, обираючи релевантний самостійно
• D. Викликаються всі інструменти одночасно, а зайві результати відкидаються

10. Підсумки та чек-лист архітектури

Model Context Protocol робить Claude Code гнучким агентським середовищем. Замість того, щоб копіювати вміст файлів чи схеми баз даних у діалог вручну, ви налаштовуєте постійні канали зв'язку один раз.

Чек-лист готовності вашого середовища

• Рівні налаштувань: Глобальні сервіси (GitHub, Web Search) винесені в ~/.claude/settings.json, а специфічні для проєкту (БД, документація) — у .claude/settings.json.
• Безпека: Токени та паролі не комітяться у відкритий репозиторій; бази даних підключені з мінімально необхідними правами (Read-Only для аналізу).
• Тестування інструментів: Робота серверів верифікована цільовими запитами після запуску сесії.
• Розширюваність: Для специфічних внутрішніх завдань створено шаблон власного сервера на TypeScript через @modelcontextprotocol/sdk.