Конфиг 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 server]
    E --> F[Issue tracker]

Полезно держать в голове и такую таблицу:

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 и проходить review как код. Тогда чужое слишком широкое подключение или подмена 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:*, не «полный доступ ко всему», а узкое право на чтение issue. Чем уже auth-scope, тем меньше радиус поражения, если что-то пойдёт не так.

В курсе почти всегда полезно начинать с read-only-режима. Если система позволяет сделать отдельный токен только для чтения задач, делайте именно так. Даже если кажется, что широкий доступ «на будущее удобнее». Удобнее — не всегда умнее. Особенно когда потом никто не помнит, зачем токену вообще разрешили половину действий системы.

Если сформулировать совсем коротко, 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": "Read-only access for Commerce OS issue analysis."
}

Сразу важная оговорка: точные имена полей могут отличаться — где-то 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 в интернете.

1

Задача

Claude code, 13 уровень, 3 лекция

Недоступна

Диагностика MCP через `/mcp status` и `/mcp debug`

Диагностика MCP через `/mcp status` и `/mcp debug`

Открыть

1

Задача

Claude code, 13 уровень, 3 лекция

Недоступна

Исправление project-scoped MCP-конфига issue tracker

Исправление project-scoped MCP-конфига issue tracker

Открыть