Врата протокола

MCP (Model Context Protocol) — открытый протокол, соединяющий агента с внешними данными и сервисами. Три роли: хост — приложение, которое инициирует соединение (здесь это Claude Code), клиент — коннектор внутри хоста, сервер — служба, отдающая контекст и возможности. Обмен идёт сообщениями JSON-RPC 2.0.

Три примитива сервера

Сервер предлагает клиенту три вида возможностей, и выбор между ними — главное проектное решение.

Со стороны клиента сервер получает одну возможность — elicitation, запрос дополнительной информации у пользователя.

Правило выбора простое. Нужно действие с эффектом — инструмент. Нужно прочитать данные — ресурс: он не тратит описание в контексте так, как инструмент, и подтягивается по адресу. Нужна заготовка разговора — промпт. Ошибка новичка — сложить всё в инструменты: перечень инструментов оплачивается контекстом каждой сессии (Котёл).

Транспорты

• stdio — локальный процесс, который хост запускает сам;
• http (он же streamable-http) — удалённый сервер, рекомендуемый вариант;
• sse — устаревший, помечен как deprecated;
• ws — веб-сокет, настраивается только через JSON.

Подключение

claude mcp add --transport http <имя> <url>
claude mcp add --transport http <имя> <url> --header "Authorization: Bearer TOKEN"
claude mcp add --transport stdio <имя> -- <команда> [аргументы...]
claude mcp add-json <имя> '<json>'

Двойное тире отделяет опции Claude Code от команды сервера. Флаги: --transport/-t, --scope/-s, --env/-e (можно несколько), --header/-H, а для OAuth — --client-id, --client-secret, --callback-port и --no-browser для SSH-сессий.

Из терминала доступны claude mcp list, claude mcp get <имя>, claude mcp remove <имя>, claude mcp login|logout <имя>, claude mcp reset-project-choices.

Три области видимости

Приоритет при совпадении имён: local → project → user → плагины → коннекторы claude.ai. Файл .mcp.json из репозитория требует одобрения — до него сервер показывается как ⏸ Pending approval.

В .mcp.json работает подстановка переменных: ${VAR}, ${VAR:-значение-по-умолчанию}, а также ${CLAUDE_PROJECT_DIR} и ${CLAUDE_PLUGIN_ROOT}. Это способ не класть токены в репозиторий.

Как обращаться

• инструменты именуются mcp__<сервер>__<инструмент> — этот же вид используется в правилах разрешений (Круг дозволенного);
• ресурс подставляется в промпт как @<сервер>:<путь-ресурса>;
• промпт сервера вызывается как /mcp__<сервер>__<промпт>;
• у плагинных серверов имена длиннее: mcp__plugin_<плагин>_<сервер>__<инструмент>.

Панель /mcp показывает состояние: ✔ Connected, ! Needs authentication, ✘ Failed to connect, ⏸ Pending approval, ⊘ Disabled for this project. Подкоманды /mcp reconnect <имя> и /mcp clear-auth <имя> решают большинство проблем с авторизацией.

Почему десять серверов — это не сразу катастрофа

По умолчанию схемы инструментов отложены: в контекст попадают только имена, а полное описание подтягивается по требованию, когда задача его действительно требует. Отключается это переменной ENABLE_TOOL_SEARCH: значение auto грузит схемы заранее, если они укладываются в 10% окна, false грузит всё.

Тайм-ауты настраиваются переменными MCP_TIMEOUT (подключение, по умолчанию около 30 секунд), MCP_TOOL_TIMEOUT (выполнение инструмента) и CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT; для отдельного сервера — поле timeout в его записи.

Дальше

Что меняется, когда сервер перестаёт быть личным экспериментом и его отдают команде, — транспорт, состояние, границы и наблюдаемость: Врата, выдерживающие команду. Как сервер приезжает к коллегам вместе с остальной настройкой — Раздача артефактов.