Конфіг MCP: transport, scope, auth, /mcp

1. MCP-конфіг як інженерний артефакт

Коли доходить до реального підключення MCP, дуже легко уявити собі туманну магію: десь щось прописали, Claude раптово побачив issue tracker, усі щасливі. У реальній роботі так краще не робити. MCP без зрозумілого конфіга — це як подовжувач без вилки: виглядає технічно, а користі мало.

Конфіг перетворює підключення на артефакт: його читають, кладуть у репозиторій, обговорюють у diff, за потреби вимикають. Такі ви вже знаєте — CLAUDE.md, SKILL.md, файл агента. MCP-конфіг фіксує, до якого сервера Claude підключається, як до нього добирається, де він живе і як проходить авторизація.

Для Workflow Kit це виглядає так:

workflow-kit/
  .claude/
    mcp/
      issue-tracker.json

Нижче — проста схема того, як мислити про конфіг:

flowchart LR
    A[mcp/issue-tracker.json] --> B[transport]
    A --> C[scope конфіга]
    A --> D[auth]
    B --> E[сервер MCP]
    E --> F[трекер задач]

Корисно тримати в голові й таку таблицю:

name

transport

endpoint

command

scope

auth

notes

Точні ключі, формат файла і навіть назви transportʼів можуть трохи відрізнятися від версії до версії. Тут важливіша не зубріння синтаксису, а сама логіка. Якщо ви відкрили mcp/issue-tracker.json, ви маєте швидко зрозуміти три речі: куди Claude йде, від чийого імені він туди йде і хто ще в команді бачить цей конфіг.

До речі, якщо ви колись побачите токен прямо всередині такого файла, це вже не «зручність». Це крик про допомогу.

2. Transport: дорога Claude до MCP-сервера

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

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

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

Локальний варіант часто зручний для швидких експериментів. Припустімо, у вас є маленький Python-скрипт, який підіймає локальний docs-server:

{
  "name": "docs-local",
  "transport": "stdio",
  "command": "python",
  "args": ["scripts/docs_server.py"]
}

Такий варіант добрий тим, що все живе поруч із вами. Мінус теж очевидний: доки сервер живе лише на вашій машині, для команди це не актив, а особиста іграшка.

Для Workflow Kit і issue-tracker нам зазвичай логічніше думати про віддалений сервер. Issue tracker — це ж не застосунок «лише у Петі під столом», а спільна зовнішня система команди:

{
  "name": "issue-tracker",
  "transport": "http",
  "endpoint": "${ISSUE_TRACKER_URL}"
}

Важливий не сам ключ http, а ідея: сервер уже існує окремо, а Claude лише підключається до нього за адресою. А на що дивитися під час вибору transport? Якщо можливість потрібна тільки вам і живе в локальному скрипті — беріть локальний процес; якщо система спільна й має працювати однаково для всієї команди — частіше виграє віддалений endpoint. mcp/issue-tracker.json — другий випадок. Інакше вийде дивно: спільний issue-analysis workflow є, а issue tracker підключений у тієї однієї людини, яка памʼятає, в якому терміналі все запускати. Це вже не Workflow Kit, а фольклор.

3. Scope: де живе конфіг і кому він належить

Після transport студенти найчастіше плутаються саме в scope. І це нормально, бо слово одне, а на практиці поруч живуть одразу два різні смисли. Scope конфіга — де лежить файл і кому доступний. Auth-scope — права токена або OAuth, наприклад read:issues. Щоб не влаштовувати інтелектуальну акробатику до обіду, далі кажу scope конфіга і auth-scope.

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

scope

user

local

project

plugin

Найважливіший для нас випадок сьогодні — project. Чому? Тому що mcp/issue-tracker.json у Workflow Kit — не особиста нотатка на холодильнику, а командний артефакт: оскільки issue-analysis skill розраховує на read-only доступ до issue tracker, підключення має бути видимим команді, лежати в Git і проходити перегляд як код. Тоді чуже надто широке підключення або підміна read-only сервера потраплять у diff раніше, ніж Claude почне вміти те, чого не повинен.

Local scope, навпаки, чудово підходить для спроб і помилок: перевіряєте новий docs lookup сервер, не впевнені у форматі, не хочете засмічувати репозиторій — робите локально, а щойно capability справді допомагає, підвищуєте до project. З plugin scope логіка подібна, тільки масштаб більший: підключення приїжджає як частина plugin-пакета — і перевіряти його потрібно так само уважно. Плагін — не священне джерело, а просто інша упаковка.

4. Auth: доступ без виставки токенів

На цьому місці в новачків часто виникає небезпечне бажання: «Ну давайте просто швидко впишемо токен прямо в JSON, щоб уже запрацювало». Бажання дуже людське. І дуже шкідливе. Добрий MCP-конфіг завжди розводить дві речі: опис способу авторизації і секретне значення, яке реально дає доступ.

Простіше кажучи, конфіг може говорити: «я використовую OAuth» або «мені потрібен endpoint зі змінної середовища». Але сам токен, секрет, пароль чи ключ у Git не кладуть. Ніколи. Навіть якщо це «лише для навчального проєкту». Саме так дрібні проблеми перетворюються на великі.

Корисний мінімум має такий вигляд:

# .env.example
ISSUE_TRACKER_URL=
ISSUE_TRACKER_TOKEN=

А в .gitignore ви зазвичай захищаєте реальні значення:

.env
.env.local
*.token
mcp/*.local.json

І вже сам конфіг посилається на ці значення, а не зберігає їх усередині:

{
  "name": "issue-tracker",
  "transport": "http",
  "endpoint": "${ISSUE_TRACKER_URL}",
  "auth": "oauth"
}

Синтаксис підстановки змінних може відрізнятися залежно від конкретної версії та інструмента. Десь це ${VAR}, десь інший формат. Тут важливо зрозуміти принцип: секрети живуть поза репозиторієм, а конфіг лише знає, що вони існують.

Тепер про auth-scope. Це вже не scope конфіга, а права самої авторизації. Наприклад, issue tracker може дозволяти токену тільки read:issues. І саме це нам потрібно для навчального Workflow Kit. Не admin:*, не «повний доступ до всього», а вузьке право на читання задач. Чим вужчий auth-scope, тим менший радіус ураження, якщо щось піде не так.

У курсі майже завжди корисно починати з режиму лише для читання. Якщо система дозволяє зробити окремий токен тільки для читання задач, робіть саме так. Навіть якщо здається, що широкий доступ «на майбутнє зручніший». Зручніше — не завжди розумніше. Особливо коли потім ніхто не памʼятає, навіщо токену взагалі дозволили половину дій системи.

Якщо сформулювати зовсім коротко, auth відповідає на запитання «як увійти в будівлю», а auth-scope — «у які кімнати вас після цього пустять». І зазвичай вам потрібен не майстер-ключ директора, а акуратний гостьовий пропуск.

5. /mcp: панель перевірки підключення

Припустімо, ви акуратно написали конфіг, прибрали секрети з репозиторію і поклали файл туди, куди треба. Наступний крок дуже простий і дуже недооцінений: не вірити на слово, що все підключилося правильно. Для цього існує службовий інтерфейс на кшталт команди /mcp або її аналога. Точна назва і набір підкоманд можуть змінюватися, але сама модель зазвичай однакова: list, get, status, debug.

На практиці це виглядає так:

/mcp list                 # показати всі підключені MCP-сервери
/mcp get issue-tracker    # відкрити деталі конкретного підключення
/mcp status               # подивитися стан і останні помилки
/mcp debug                # увімкнути докладнішу діагностику

Не тримайтеся за ці назви як за заповіді, викарбувані в камені — у вашій версії формулювання можуть відрізнятися. Але сама логіка корисна в будь-якій версії Claude Code.

List відповідає на найпростіше запитання: чи бачить система ваш MCP-сервер взагалі. Get допомагає перевірити конкретне підключення: що за transport, який endpoint, який опис. Status потрібен, коли «ніби налаштували, а нічого не працює». Часто саме там видно, що проблема не в skill, не в Claude і не у фазах Місяця, а в неправильній адресі, зламаній авторизації або недоступному сервері. Debug уже стане у пригоді, коли потрібна докладніша розмова з діагностикою та логами.

Тут є одне дуже корисне професійне правило. Якщо get_issue не працює, не починайте з переписування половини workflow. Спочатку перевірте /mcp. Дуже часто проблема буденна і приземлена: неправильний endpoint, не той scope, забута змінна середовища, прострочений токен. І все це краще виправляти на рівні підключення, а не будувати поверх нього нові шари хаосу.

Для нашого Workflow Kit це особливо важливо. Уявіть, що skill issue-analysis раптово перестав «бачити» задачу Commerce OS. Не потрібно одразу звинувачувати skill у зраді. Можливо, issue-tracker просто не піднявся або не пройшов auth. Діагностика через /mcp економить масу часу і, що ще приємніше, масу драматичних монологів у термінал.

6. Збираємо mcp/issue-tracker.json для Workflow Kit

Тепер зберемо в один артефакт той самий read-only issue-tracker, який ми вже виправдали для issue-analysis. Нам потрібен project-scoped MCP-конфіг у Workflow Kit. Задача в нього дуже конкретна — перестати копіювати опис issue вручну і дати Claude можливість читати задачі з зовнішньої системи контрольованим способом.

Навчальний варіант конфига може виглядати так:

{
  "name": "issue-tracker",
  "transport": "http",
  "endpoint": "${ISSUE_TRACKER_URL}",
  "auth": "oauth",
  "authScopes": ["read:issues"],
  "tools": [
    { "name": "list_issues", "permissions": "read-only" },
    { "name": "get_issue", "permissions": "read-only" },
    { "name": "search_issues", "permissions": "read-only" }
  ],
  "notes": "Доступ лише для читання для аналізу задач Commerce OS."
}

Одразу важлива заувага: точні назви полів можуть відрізнятися — десь tools підтягуються із сервера самі, десь authScopes оформлені інакше. Але як навчальна модель читання конфіг ідеальний: у ньому видно всі рішення — віддалений сервер, OAuth, звужені до читання права, три read-only tool без жодної write-операції. А notes пояснює, навіщо підключення існує, щоб через місяць ніхто не гадав про ще один JSON-файл.

Якщо ви покладете файл у workflow-kit/.claude/mcp/issue-tracker.json, закомітите без секретів і перевірите через /mcp, замість розмовної ідеї «треба підключити issue tracker» зʼявиться інженерний актив команди: його можна переглядати, обговорювати, поліпшувати, повторно використовувати. А skill issue-analysis перестане залежати від копіювання з браузера і спиратиметься на читабельний, прозорий, обмежений шар можливостей.

Це і є головний результат лекції. Усе, що здавалося туманною магією «десь щось прописали», розкладається на чотири читабельні рішення в одному файлі: transport — як Claude добирається до сервера, scope конфіга — де файл живе і хто його бачить, auth із посиланням на env — від чийого імені і з якими правами йде запит, /mcp — чим ви це перевіряєте, коли «ніби налаштували, а не працює». Відкрили issue-tracker.json, прочитали ці чотири відповіді за хвилину — отже, конфіг написаний по-інженерному, а не скопійований із випадкового JSON в інтернеті.