MCP в Claude Code: как подключить серверы, не сжечь контекст и когда он не нужен

Коротко (TL;DR)

MCP-сервер даёт Claude Code доступ к внешнему сервису или данным — базе Postgres, репозиториям на GitHub, задачам в Jira, дизайну в Figma, поиску в вебе. Подключается одной командой claude mcp add, работает через один из трёх транспортов (stdio, http, sse) и живёт на одном из трёх уровней видимости (local, project, user).

Важное, чего почти не пишут в русскоязычных гайдах: MCP не бесплатен по контексту. Одно определение инструмента стоит примерно 500–2000 токенов, а насыщенный сервер вроде GitHub — до 26 000 токенов на одни только описания своих инструментов (данные Anthropic на 24 ноября 2025). Пять таких серверов — и модель тратит 55 000+ токенов ещё до того, как прочитает ваш запрос. Именно эту проблему решает Tool Search: он откладывает загрузку описаний и подтягивает нужный инструмент по требованию, сокращая расход с ~77 000 до ~8,7 тыс. токенов — минус 85%. С января 2026 он включён в Claude Code по умолчанию.

И главный вопрос, который стоит задать до установки любого сервера: а нужен ли тут вообще MCP? Часто дешевле по токенам и надёжнее обычная Bash-команда или Skill. Ниже — команды по шагам, таблица решения «MCP vs CLI vs Skill» и честный разбор рисков, включая архитектурную уязвимость STDIO, о которой Anthropic заявила, что менять её не будет.

Данные проверены по официальной документации Claude Code и инженерным материалам Anthropic на 11 июля 2026 года. Самое изменчивое здесь — номера версий CLI и точные цифры экономии токенов: сверяйте их в code.claude.com/docs/en/mcp перед настройкой продакшена.

SpaceX · xStockSpaceX — частная компания. Торгуй её токеном на Bybit за крипту.Торговать SpaceX →

Что такое MCP в контексте Claude Code

MCP (Model Context Protocol) — это открытый стандарт, по которому ИИ-агент подключается к внешним источникам данных и инструментам. Anthropic открыла его 25 ноября 2024 года; авторы протокола — David Soria Parra и Justin Spahr-Summers. Идея простая: вместо того чтобы под каждый сервис писать отдельную интеграцию, вы поднимаете «сервер», который говорит на общем языке, — и любой MCP-клиент (Claude Code, Claude Desktop, Cursor и десятки других) умеет с ним работать.

Хуки Claude Code: как автоматизировать действия агента и не подорваться на своих же настройках

Плагины в Claude Code: как установить, создать свой маркетплейс и не поймать вредоносный

SKILL.md без магии: собираем свой скилл Claude Code по инженерным паттернам

Agent Skills в Claude Code: как работают, где взять и как не поставить вредоносный скилл

Память Claude Code: Auto Memory, /memory и почему агент забывает

За год протокол стал одним из самых быстрорастущих опенсорс-проектов в ИИ: более 97 млн загрузок SDK в месяц и 10 000 активных серверов на 9 декабря 2025 года (данные официального блога MCP). Тогда же Anthropic передала управление протоколом в Agentic AI Foundation — фонд под эгидой Linux Foundation, соучреждённый Anthropic, Block и OpenAI при поддержке Google, Microsoft, AWS, Cloudflare и Bloomberg. То есть MCP перестал быть «фичей одного вендора» и стал отраслевым стандартом.

В Claude Code MCP — это не магия «подключил и работает», а инженерное решение с ценой и рисками. Сервер — отдельный процесс (локальный или удалённый), который отдаёт агенту набор инструментов: «прочитать таблицу», «создать issue», «сделать запрос к API». Claude Code сам решает, когда их вызвать. Ваша задача — правильно этот сервер подключить, не перегрузив контекст, и понимать, кому вы доверяете исполнение на своей машине.

Если вам не хватает базового понимания, что вообще такое протокол и зачем он нужен, — это отдельная тема; здесь мы считаем, что с основами вы знакомы, и сразу переходим к практике настройки.

Три транспорта: как сервер общается с Claude Code

Транспорт — это способ, которым Claude Code обменивается сообщениями с сервером. Спецификация MCP определяет два стандартных механизма — stdio и Streamable HTTP; старый транспорт HTTP+SSE (версия протокола 2024-11-05) объявлен устаревшим и заменён на Streamable HTTP. Claude Code при этом на уровне CLI поддерживает добавление серверов по трём транспортам плюс WebSocket через отдельную команду.

Практическое правило: для локального инструмента берите stdio, для облачного — http; sse — только если сервер не умеет иначе. Новые серверы поднимайте на HTTP.

Как подключить MCP-сервер: пошагово

Разберём три способа добавить сервер — через claude mcp add, через файл .mcp.json и через выбор уровня видимости. Дальше — аутентификация для удалённых серверов.

Bybit · Rewards Hubдо $30,100Внеси депозит, торгуй 14 дней — и забери награды в Rewards HubЗабрать бонус →

Шаг 1. Команда claude mcp add под каждый транспорт

Базовый синтаксис одинаков для всех транспортов, меняется флаг --transport и то, что идёт после имени:

# Локальный stdio-сервер (транспорт по умолчанию)
claude mcp add my-server -- npx -y @modelcontextprotocol/server-filesystem ~/projects

# Удалённый HTTP-сервер
claude mcp add --transport http linear https://mcp.linear.app/mcp

# Удалённый SSE-сервер (устаревший транспорт)
claude mcp add --transport sse legacy-server https://example.com/sse

Двойное тире -- перед командой stdio-сервера обязательно: всё, что после него, Claude Code запускает как отдельный процесс. После добавления проверьте статус командой claude mcp list (покажет connected или ошибку) и claude mcp get <name> для деталей.

Есть зарезервированные имена, которые нельзя занимать своими серверами: workspace, claude-in-chrome, computer-use, Claude Preview и Claude Browser заняты встроенными серверами Claude Code — конфиг с таким именем просто пропускается при загрузке.

Шаг 2. Выберите scope (уровень видимости)

Scope определяет, где хранится конфиг сервера и кто его видит. Это тонкое место, где чаще всего путаются.

Задаётся флагом -s (или --scope):

claude mcp add -s project github-server -- npx -y @modelcontextprotocol/server-github
claude mcp add -s user my-notes -- npx -y some-personal-server

Логика выбора: local — личный черновик под конкретный проект; project — общий для команды сервер, который коммитится в репозиторий (.mcp.json), чтобы у всех была одинаковая среда; user — личный инструмент, который нужен во всех проектах сразу (например, MCP-сервер поиска или ваша персональная база знаний).

Если один и тот же сервер задан на нескольких уровнях, Claude Code подключается к нему один раз, беря определение с самого приоритетного уровня. Порядок приоритета: local → project → user → серверы из плагинов → коннекторы claude.ai.

Шаг 3. Файл .mcp.json и переменные окружения

Project-scope пишет конфиг в .mcp.json в корне репозитория. Его можно править руками — удобно для команды и для секретов, которые нельзя хардкодить. MCP поддерживает подстановку переменных окружения:

• ${VAR} — подставляет значение переменной VAR;
• ${VAR:-default} — значение VAR, а если она не задана — дефолт.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_HOST": "${GITHUB_HOST:-github.com}"
      }
    }
  }
}

Так токен не попадает в git, а каждый разработчик подставляет свой из окружения. Отдельная тонкость, на которой спотыкаются даже опытные: .mcp.json (project-scope) и ~/.claude.json (local/user-scope) — это не то же самое, что .claude/settings.local.json. Последний — общие настройки Claude Code, а не место для MCP-серверов. Ищете сервер не там — не найдёте.

Шаг 4. Аутентификация удалённых серверов (OAuth 2.0)

Облачные серверы обычно требуют вход. Claude Code помечает удалённый сервер как «нужна аутентификация», когда тот отвечает 401 Unauthorized или 403 Forbidden. Дальше:

• войти интерактивно — команда /mcp внутри сессии;
• войти из шелла — claude mcp login <name> (доступно с версии v2.1.186), запускает OAuth-флоу сервера прямо из терминала.

Важно: OAuth работает только для транспортов http и sse. Для stdio-серверов эти флаги не имеют эффекта — локальный процесс аутентифицируется своими средствами (например, токеном в переменной окружения).

Tool Search: зачем он и что даёт в цифрах

Вот проблема, ради которой всё это существует. Каждый MCP-сервер вставляет описания своих инструментов прямо в контекст модели. По данным инженерного блога Anthropic (24 ноября 2025), типичная пятисерверная связка выглядит так: GitHub — 35 инструментов (~26 тыс. токенов), плюс Slack, Jira и прочее — в сумме 58 инструментов и около 55 тыс. токенов ещё до того, как начался разговор. Внутри Anthropic видели раздувание до 134 тыс. токенов только на определениях. Это не абстракция: чем больше контекста занято описаниями, тем меньше остаётся под работу и тем сильнее падает точность модели.

Tool Search переворачивает схему: описания инструментов не грузятся заранее, а обнаруживаются по требованию. Модель сначала ищет нужный инструмент по короткому индексу и подгружает полное определение только того, что реально собирается вызвать.

Цифры из внутренних тестов Anthropic (на 24 ноября 2025):

Обратите внимание: экономия токенов не просто «удешевляет» работу — она поднимает точность, потому что модель не тонет в тысячах описаний, которые ей сейчас не нужны. Это редкий случай, когда оптимизация по стоимости и по качеству идут в одну сторону.

Отдельно про абсолютные числа: VentureBeat со ссылкой на разбор в сообществе приводит другую пару — 134 тыс. → 5 тыс. токенов. Расхождение с официальными 77 тыс. → 8,7 тыс. объясняется разным набором серверов в тесте; итоговый процент сокращения (85%) совпадает в обоих случаях.

В Claude Code Tool Search стал публично доступен 14–15 января 2026 года — это была одна из самых запрашиваемых сообществом фич (GitHub-запрос на «умное представление инструментов» набрал десятки апвоутов задолго до релиза). Управление — через переменную ENABLE_TOOL_SEARCH (true/false/auto/auto:N). Одно ограничение: функция требует модель с поддержкой блоков tool_reference — модели Haiku её не поддерживают. Если какой-то инструмент нужен всегда и его не должен «искать» агент, для него можно задать alwaysLoad — тогда он грузится сразу, в обход отложенного поиска.

Когда MCP нужен, а когда лучше CLI или Skill

Это раздел, который отличает практика от евангелиста. MCP — не единственный способ дать Claude Code новую возможность, и часто не лучший. Есть три инструмента с разной ценой и назначением.

Официальное разграничение Anthropic звучит так: «MCP подключает Claude к внешним сервисам. Skills расширяют то, что Claude знает, — включая то, как этими сервисами эффективно пользоваться. Это разные задачи, и они хорошо работают вместе». Проще: MCP даёт доступ, Skill даёт знание, обычная CLI-команда даёт разовое действие.

Цена вопроса в токенах (порядок величины, оценка стороннего анализа — не официальная метрика Anthropic, но масштаб совпадает с цифрами по 50+ инструментам): одно определение MCP-инструмента — ~500–2000 токенов в контексте; эквивалентный Skill — ~200 токенов при загрузке и ноль, когда не используется. Bash-команда не стоит ничего, пока вы её не вызвали.

Дерево решения:

Практический тест: если задачу закрывает curl или существующий CLI-клиент, а вызывать его нужно изредка — не поднимайте MCP-сервер, вы просто добавите 26 тыс. токенов постоянного оверхеда ради того, что решается одной командой. MCP оправдан, когда сервис нужен часто, операций много, и вы хотите, чтобы агент сам выбирал нужную из структурированного набора — например, Slack как MCP-сервер для постоянной работы с сообщениями или сервер к вашей персональной базе знаний.

Где ломается: типичные ошибки

У евангелистов всё всегда работает. В реальности MCP-серверы отваливаются по предсказуемым причинам.

Отдельно про переподключение: HTTP и SSE-серверы Claude Code восстанавливает автоматически с экспоненциальной задержкой, а stdio — локальные процессы — сами не поднимаются. Если локальный сервер упал, его нужно перезапустить.

Риски и безопасность: кому вы доверяете исполнение

Это YMYL-часть, и здесь мы не сглаживаем. MCP-сервер — это код, который выполняется на вашей машине с вашими правами. Точная и честная рамка: сервер может делать то же, что можете вы — читать ваши файлы, ходить в сеть, дёргать API от вашего имени. Отсюда три реальных риска.

1. Архитектурная уязвимость STDIO (supply chain). 15 апреля 2026 года OX Security опубликовала разбор системной уязвимости в транспорте STDIO: возможность инъекции команд и удалённого выполнения кода (RCE). Это не баг одного сервера, а поведение, заложенное во всех официальных SDK (Python, TypeScript, Java, Rust). Масштаб цепочки поставок: 150 млн+ загрузок, 7000+ публично доступных серверов, до 200 000 потенциально уязвимых инстансов, 10+ выпущенных CVE. Anthropic подтвердила поведение как «дизайн-решение» и «безопасный дефолт», отказавшись менять протокол: санитизация ввода — ответственность разработчика конкретного сервера.

Что это значит для вас без паники: риск в основном касается серверов, которые сами передают непроверенный пользовательский ввод в аргументы команд, а не любого stdio-сервера по умолчанию. Практический вывод — ставьте stdio-серверы только из источников, которым доверяете, и не запускайте случайные пакеты с непонятной репутацией.

2. Tool poisoning (отравление инструментов). В начале 2026 года Snyk Security Labs задокументировала атаку, где вредоносное описание MCP-инструмента заставляло агента выгружать данные репозитория GitHub на сервер злоумышленника — без дополнительных действий пользователя. Вектор — поле description инструмента: агент читает его как инструкцию и выполняет. Урок: описание инструмента — это тоже входные данные, и недоверенный сервер может вписать туда что угодно.

3. Prompt injection через контент. Серверы, которые тянут внешний контент (документацию, веб-страницы, тикеты), могут принести в контекст модели скрытую инструкцию. Этот общий риск независимо отмечают технические разборы (например, dou.ua): если MCP-сервер забирает непроверенный текст, в нём может быть встроенная команда агенту.

Отдельно стоит держать в голове масштаб экосистемы как фактор риска. Оценки числа серверов расходятся: 10 000 по официальному реестру (декабрь 2025) против ~7000 «в дикой природе» по скану OX Security (начало 2026). Это не ошибка, а разные методики подсчёта — но сам разброс показывает, насколько велика и слабо контролируема цепочка поставок. Практика безопасности: минимум одновременно активных серверов, project-scope с явным доверием, никаких секретов в .mcp.json напрямую (только через ${VAR}), и здоровая паранойя к незнакомым пакетам.

Продвинутый приём: code execution вместо прямых вызовов

Если Tool Search экономит контекст на описаниях, то следующий уровень — экономия на результатах. Anthropic описала подход (4 ноября 2025), при котором модель не вызывает MCP-инструменты напрямую, а пишет код на TypeScript или Python, который сам дёргает эти инструменты в изолированной среде. Промежуточные результаты не заваливают контекст: модель получает только финальный ответ. На собственном примере Anthropic это дало экономию до 98,7% (со 150 000 до 2 000 токенов); Cloudflare независимо описала тот же подход, назвав его Code Mode. Приём не для каждой задачи, но там, где агент делает много последовательных вызовов с большими выхлопами, он радикально меняет стоимость работы.

FAQ

Чем MCP в Claude Code отличается от коннекторов в claude.ai? Это разные поверхности продукта. Коннекторы в claude.ai и Claude Desktop — потребительский интерфейс: вы выбираете сервис (Gmail, Calendar, Notion) из каталога и даёте права кликами. MCP в Claude Code — разработческий уровень: вы сами поднимаете серверы командой claude mcp add, управляете транспортами, scope и .mcp.json. Под капотом протокол один, но управление и гибкость разные.

Нужно ли включать Tool Search вручную? Нет. В Claude Code он включён по умолчанию с середины января 2026 года — опт-ин не требуется. Управлять поведением можно переменной ENABLE_TOOL_SEARCH. Единственное ограничение — модель должна поддерживать блоки tool_reference; модели Haiku их не поддерживают, там Tool Search не работает.

Почему мой project-сервер висит в статусе Pending approval? С версии v2.1.196 сервер, заданный в .mcp.json, не запускается в недоверенном репозитории, пока вы явно не доверите workspace. Это защита от того, чтобы клонированный чужой репозиторий не поднял произвольный сервер у вас на машине. Подтвердите доверие к проекту — сервер запустится.

Сколько MCP-серверов можно держать включёнными одновременно? Технически ограничения нет, но каждый сервер занимает контекст под описания инструментов (насыщенный — десятки тысяч токенов). До Tool Search это была прямая проблема; сейчас отложенная загрузка снимает основную нагрузку. Всё равно правило безопасности и гигиены контекста — держать активными только реально нужные серверы, а не «на всякий случай».

Можно ли обойтись без MCP вообще? Часто да. Если задача — разовое или скриптуемое действие, обычная Bash/CLI-команда дешевле и надёжнее (ноль токенов на определения). Если нужно научить агента процессу или стандарту — это Skill. MCP оправдан, когда нужен постоянный структурированный доступ к внешнему сервису с множеством операций.

Безопасно ли подключать сторонние MCP-серверы? С оговорками. Сервер выполняется с вашими правами и может то же, что и вы. Риски реальны: архитектурная уязвимость STDIO (OX Security, апрель 2026), отравление описаний инструментов (Snyk), prompt injection через приносимый контент. Ставьте серверы только из источников, которым доверяете, не храните секреты открытым текстом в .mcp.json и держите минимум активных серверов.