MCP - Model Context Protocol - подключает к Claude Code внешние инструменты, ресурсы и промпты. Ключевое, что нужно держать в голове: MCP-сервер - это отдельная граница доверия. Он получает ровно те данные и полномочия, что даёт его протокол, и потому к нему относятся как к стороннему коду: читают его исходники или условия провайдера и выдают минимальный доступ. Подключить сервер "для удобства", не понимая, что он может делать, - значит расширить поверхность риска вслепую.
Транспортов несколько, и у каждого своя роль. HTTP - рекомендуемый удалённый транспорт для request-response; SSE устарел и нужен лишь для legacy-эндпоинта. stdio запускает локальный процесс, и здесь важен разделитель: двойное тире отделяет флаги Claude от команды сервера. WebSocket задаётся через JSON, годится для push и не поддерживает OAuth. Управляют серверами командами claude mcp add, list, get и remove - от добавления до проверки и удаления.
Scopes определяют, кто видит сервер и где он хранится. local (по умолчанию) лежит в ~/.claude.json внутри записи проекта и виден только вам в одном проекте. project - в .mcp.json, виден команде после доверия и одобрения. user - в ~/.claude.json, виден вам во всех проектах. managed - политика организации. При совпадении имени приоритет: local, project, user, plugin, затем claude.ai-коннекторы; берётся целая запись, поля не сливаются. Проектный .mcp.json требует явного approval, а сброс выбора - команда reset-project-choices.
| Scope | Storage | Видимость |
|---|---|---|
| local (default) | ~/.claude.json в записи проекта | Только вы, один проект |
| project | .mcp.json | Команда после trust/approval |
| user | ~/.claude.json | Только вы, все проекты |
| managed | managed MCP policy | Организация |
Секреты в MCP-конфигурации держат вне репозитория. Полезно один раз увидеть запись .mcp.json с подстановкой переменных: url и заголовок Authorization берут значения из окружения через синтаксис с переменной и значением по умолчанию, а не хранят токен буквально. Подстановка поддерживается в command, args, env, url и headers. Правило простое и жёсткое: literal-токен в .mcp.json - это утёкший секрет, поэтому ссылаются на переменную, а сам секрет инъектируют из окружения или secret-store.
Аутентификация и здоровье сервера - отдельная проверка. Удалённый HTTP-сервер может использовать OAuth: запускают /mcp или соответствующий auth-flow и проходят браузерную авторизацию. Важная тонкость: claude mcp list различает configured и connected - статус Added означает лишь, что конфиг записан, а не что handshake удался. Проверяют health, число инструментов, аутентификацию и реальные возможности чтения и записи, а не верят самому факту добавления.
Инструменты, ресурсы и промпты приходят с понятной семантикой. Инструменты появляются под именами вида mcp__server__tool и проходят обычный permission flow; сервер может пометить инструмент как требующий взаимодействия, и тогда подтверждение сохраняется даже в широком режиме. Ресурсы упоминают через собаку и URI, а MCP-промпты становятся динамическими slash-командами. Elicitation позволяет серверу запросить структурированный ввод во время вызова - но собирать через свободный промпт секреты, не проверив протокол и получателя, нельзя.
Стартовый контекст экономит tool search. Большой MCP-вывод обрезается по лимитам, поэтому задачу сервера лучше проектировать с пагинацией. Tool search откладывает схемы редко используемых инструментов и подгружает нужные по запросу, резко снижая стартовый контекст; совместимые модели включают механизм автоматически, а gateway обязан пропускать protocol-блоки. alwaysLoad оставляют только для небольших критичных серверов.
Главное предупреждение: MCP - это не "просто данные". Инструмент с правом записи может отправлять сообщения, менять тикеты, базу данных или инфраструктуру - то есть действовать во внешних системах от вашего имени. Поэтому к таким серверам добавляют точечные ask и deny по инструментам, sandbox или тестовый аккаунт провайдера и audit trail. Типичные провалы - literal-токен в .mcp.json, доверие статусу Added вместо проверки connected и write-capable сервер без узких правил. Выдавайте минимальный доступ и проверяйте фактические полномочия.
{
"mcpServers": {
"internal-docs": {
"type": "http",
"url": "${DOCS_MCP_URL:-https://docs.example.com/mcp}",
"headers": { "Authorization": "Bearer ${DOCS_MCP_TOKEN}" }
}
}
}
// подстановка ${VAR} / ${VAR:-default}; literal-токен коммитить нельзя