Claude Code хорошо работает с тем, что лежит в файловой системе: читает код, правит файлы, запускает команды. Но реальная задача редко ограничивается репозиторием. Тикет живёт в трекере, данные — в базе, поведение продукта проверяется в браузере. Каждый переход вы делаете руками: копируете описание задачи в чат, выполняете SQL и вставляете результат, открываете страницу и пересказываете агенту, что видите.

MCP убирает эти ручные мостики: вместо пересказа вы даёте агенту инструмент, которым он пользуется сам.

Что уже умеем / что добавим

В восьмой главе вы получили детерминированный контроль над тем, что происходит внутри Claude Code: хук срабатывает всегда, независимо от того, вспомнила о нём модель. Это контроль вглубь — над существующим набором действий.

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

Что вы узнаете в рамках статьи

• Как устроена связка «клиент — сервер» в Model Context Protocol
• Чем различаются транспорты http, stdio и sse и когда какой выбирать
• Как устроен файл .mcp.json и какая ошибка в нём самая частая
• Что такое области видимости local, project и user и как решается конфликт имён
• Как проверить подключение и во сколько контекста обходится сервер

Ключевые термины

• MCP (Model Context Protocol) — открытый стандарт интеграции AI с внешними инструментами и источниками данных.
• MCP-клиент — сторона, которая подключается к серверам и вызывает их инструменты. Здесь это Claude Code.
• Транспорт — способ связи клиента с сервером: http, stdio или устаревший sse.
• MCP-сервер — внешняя система, дающая Claude Code доступ к вашим инструментам, базам данных и API. Работает либо локально, либо как размещённый сервис.
• Область видимости (scope) — уровень, на котором сохранена запись о сервере: local, project или user. Определяет, где лежит конфигурация и кому она доступна.

Клиент, серверы и три транспорта

Схема простая. Claude Code — клиент. Каждая подключаемая система — сервер, который объявляет набор инструментов; клиент их видит и вызывает. Что сервер умеет, решает его автор.

Сервер бывает размещённым сервисом по URL или программой, которую Claude Code запускает как подпроцесс. Первый вариант удобен для облачных продуктов, второй нужен там, где инструменту требуется доступ к локальным ресурсам — браузеру, файловой системе, сокету базы данных.

Отношение работает и в обратную сторону: Claude Code умеет быть MCP-сервером.

claude mcp serve

Команда запускает Claude Code как stdio-сервер, отдающий его инструменты вашему MCP-клиенту. Оговорка из документации: такой сервер только предоставляет инструменты, а за подтверждение вызовов отвечает клиент.

Транспорт связи задаётся флагом --transport при добавлении сервера.

claude mcp add --transport http notion <https://mcp.notion.com/mcp>
claude mcp add --transport http secure-api <https://api.example.com/mcp> \
  --header "Authorization: Bearer your-token"

HTTP — рекомендуемый транспорт для размещённых сервисов: указываете конечную точку и при необходимости заголовок с токеном.

SSE — устаревший. Он поддерживается (claude mcp add --transport sse <name> <url>), но документация советует HTTP везде, где он доступен.

stdio — локальный процесс и транспорт по умолчанию, флаг можно не указывать:

claude mcp add playwright -- npx -y @playwright/mcp@latest
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Отдельно про --. Разделитель отделяет опции команды claude (--transport, --env, --scope) от команды запуска сервера. Всё после -- передаётся серверу без изменений, вместе с его флагами: именно поэтому -y выше достаётся npx, а не Claude Code. Пропущенный -- — частая причина ошибки: без него аргументы сервера разбираются как опции claude mcp add.

Файл .mcp.json

Серверы области project описываются файлом .mcp.json в корне проекта. Он коммитится, и клонирующие репозиторий получают тот же набор.

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "<https://code.claude.com/docs/mcp>"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Для HTTP-сервера ключевое поле — url. Для stdio-сервера — command и args: программа, которую Claude Code запустит, и её аргументы. То, что в командной строке шло после --, здесь раскладывается по этим полям.

Самая частая ошибка здесь — запись с url, но без type. Claude Code читает её как stdio-сервер, пропускает и сообщает: MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Остальные серверы загрузятся, поэтому пропажу легко не заметить.

Файл читается при старте сессии, поэтому после правки её нужно перезапустить.

Области видимости и порядок приоритета

Запись о сервере может жить в трёх местах.

claude mcp add --transport http stripe --scope local <https://mcp.stripe.com>
claude mcp add --transport http shared-server --scope project <https://example.com/mcp>
claude mcp add --transport http hubspot --scope user <https://mcp.hubspot.com/anthropic>

Если сервер с одним именем объявлен в нескольких местах, приоритет такой: local, project, user, затем серверы от плагинов и в конце коннекторы claude.ai. Берётся целиком запись из источника-победителя: поля из разных областей не сливаются, так что «url возьму из project, а заголовок из user» не сработает.

Две оговорки. Первая: «local» у MCP — это не .claude/settings.local.json, а ~/.claude.json; настройки и конфигурация MCP живут отдельно. Вторая: область фиксируется при добавлении и меняется только удалением записи и повторным добавлением с другим --scope.

Проверка, диагностика и цена контекста

Посмотреть, что подключено, можно из shell:

claude mcp list        # список серверов и статусы подключения
claude mcp get stripe  # детали одного сервера, включая его область

Внутри сессии ту же картину даёт /mcp: список серверов, статус каждого и число инструментов рядом с подключённым. Возможные статусы — Connected, Needs authentication, Failed to connect, Pending approval, Disabled for this project.

Серверы подключаются при старте сессии. Таймаут — 30 секунд, меняется переменной MCP_TIMEOUT в миллисекундах:

MCP_TIMEOUT=60000 claude

Первый запуск stdio-сервера бывает медленным: пока npx скачивает пакет, подключение может не уложиться в таймаут, и первая claude mcp list покажет Failed to connect. Это нормально.

Теперь про цену. В главе про управление контекстом вы видели, что контекстное окно — исчерпаемый ресурс. Каждый подключённый сервер занимает место: имена его инструментов и инструкции загружаются в каждую сессию. Отсюда правило гигиены — удаляйте неиспользуемые серверы. Частично помогает tool search: он включён по умолчанию и позволяет не загружать все определения заранее, Claude находит нужный инструмент вызовом ToolSearch.

Как называются инструменты MCP

Инструмент сервера получает полное имя вида mcp__<сервер>__<инструмент>: например, mcp__github__search_repositories или mcp__filesystem__read_file.

Это имя используется везде, где вы уже работали с инструментами: в правилах разрешений, в списке allowed-tools скилла, в поле tools подагента и в матчере хука. Механики из глав про разрешения, скиллы, подагентов и хуки работают с MCP без изменений — меняется только форма имени. К правам вернёмся в уроке 9.5.

Частые ошибки

• Запись с url, но без type в .mcp.json. Claude Code считает её stdio-сервером и пропускает с предупреждением. Указывайте "type": "http".
• Пропущенный -- при добавлении stdio-сервера. Без разделителя аргументы команды запуска разбираются как опции claude mcp add. Ставьте -- сразу после имени сервера.
• Правка конфигурации не по тому пути. Claude Code не читает ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json. Верных путей два: ~/.claude.json и <project>/.mcp.json.
• Подключать серверы про запас. Каждый расходует контекст в каждой сессии. Держите подключённым то, чем пользуетесь.

Наиболее частые вопросы

• Какой транспорт выбрать? — Если у сервиса есть URL, берите http. Если инструменту нужен локальный ресурс вроде браузера или сокета базы — stdio. sse устарел.
• Я поправил .mcp.json, а ничего не изменилось. — Файл читается при старте сессии. Перезапустите её.
• Можно ли перенести сервер из local в project? — Не напрямую: удалите запись и добавьте заново с нужным --scope.
• Сервер объявлен и в .mcp.json, и локально. Какой сработает? — Локальный: приоритет у local. Запись берётся целиком, поля не смешиваются.
• claude mcp list показывает Failed to connect у нового stdio-сервера. — Вероятно, npx ещё скачивает пакет. Повторите позже или увеличьте MCP_TIMEOUT.

Итоги

Вы разобрали архитектуру MCP: Claude Code в роли клиента, внешние системы в роли серверов, три транспорта и правило выбора между ними. Вы знаете, как выглядит .mcp.json, чем local отличается от project и user и как читается приоритет при конфликте имён. Вы умеете проверить подключения через claude mcp list и /mcp и помните про расход контекста.

Дальше практика: подключим реальные серверы, разберёмся с аутентификацией и доверием к чужим конфигурациям, а затем настроим права так, чтобы внешние инструменты работали в заданных вами границах.