- Как работает настройка Claude MCP
- Добавление MCP-серверов в Claude Code
- Конфигурация MCP-серверов в Claude Desktop
- Типы MCP-транспорта: stdio vs SSE
- Как Claude принимает решения об MCP-инструментах
- Выполнение инструментов в изолированной среде (песочнице)
- Использование Novita LLM API для принятия решений об MCP-инструментах
- Часто встречающиеся проблемы и их решения
- Часто задаваемые вопросы (FAQ)
- Рекомендуемые статьи
Настройка Claude MCP подключает Claude Code или Claude Desktop к внешним инструментам, таким как базы данных, раннеры кода, API и пользовательские серверы. Используйте claude mcp add для Claude Code или редактируйте JSON-конфигурацию Claude Desktop, затем проверьте транспорт, область видимости и список инструментов. Это руководство охватывает оба пути настройки, типичные ошибки, логику использования инструментов и выполнение в изолированной среде.
Как работает настройка Claude MCP
MCP — это открытый стандарт от Anthropic, который предоставляет языковым моделям единый способ вызова внешних инструментов. До MCP каждому AI-приложению требовался собственный связующий код для каждого используемого инструмента. С MCP любой совместимый сервер предоставляет свои возможности через стандартный протокол обнаружения и вызова, и любой совместимый хост — включая Claude — может их использовать без необходимости интеграции под каждый инструмент.
На практике: когда вы добавляете MCP-сервер в Claude, вы сообщаете хосту Claude, где найти набор инструментов. Claude может затем перечислить эти инструменты во время сессии и вызывать их по имени, когда это необходимо для выполнения задачи. Сервер отвечает за выполнение; Claude отвечает за принятие решений о том, когда и как вызывать.
Три основных понятия лежат в основе MCP:
| Понятие | Что это | Пример |
|---|---|---|
| Инструмент (Tool) | Вызываемая функция, предоставляемая сервером | run_python, query_db, list_models |
| Ресурс (Resource) | Данные только для чтения, которые сервер предоставляет в качестве контекста | Файл, строка базы данных, набор данных |
| Промпт (Prompt) | Предварительно созданные шаблоны инструкций, входящие в состав сервера | Описание задачи на уровне системы |
Для большинства разработчиков наиболее важны инструменты. Ресурсы и промпты становятся актуальными при создании более структурированного конвейера агентов.
Добавление MCP-серверов в Claude Code
Claude Code предоставляет управление MCP через группу подкоманд claude mcp. Вы можете добавлять, удалять и просматривать серверы без ручного редактирования конфигурационных файлов.
claude mcp add — базовая форма
claude mcp add <имя> <команда> [аргументы...]
Например, чтобы добавить локальный Python MCP-сервер:
claude mcp add my-tools python /path/to/mcp_server.py
Это регистрирует сервер с именем my-tools, который запускает python /path/to/mcp_server.py, используя stdio-транспорт. Claude Code запускает процесс при начале сессии и поддерживает его активным на время её работы.
Передача переменных окружения
Многие MCP-серверы требуют API-ключи или URL-адреса конечных точек. Используйте --env для их передачи при регистрации:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=your_key_here \
--env BASE_URL=https://api.example.com
Значения сохраняются в конфигурации Claude Code и внедряются в процесс сервера при запуске. Не встраивайте секреты напрямую в команду сервера.
claude mcp add json — регистрация из JSON-спецификации
Если у вас уже есть спецификация сервера в формате JSON (распространено при обмене конфигурациями в команде), вы можете передать её напрямую:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key"
}
}' | claude mcp add my-tools --json
Или передать файл:
claude mcp add my-tools --json < server-spec.json
Это эквивалентно позиционной форме, но даёт единый конфигурационный артефакт, который можно версионировать и распространять.
Просмотр и удаление серверов
# Просмотреть все зарегистрированные серверы
claude mcp list
# Удалить сервер
claude mcp remove my-tools
Область видимости: проект или пользователь
По умолчанию claude mcp add регистрирует сервер в пользовательской конфигурации, делая его доступным в каждой сессии Claude Code. Чтобы зарегистрировать его только для текущего проекта (хранится в .claude/settings.json), добавьте --scope project:
claude mcp add my-tools python /path/to/mcp_server.py --scope project
Серверы с областью видимости проекта полезны, когда разным проектам нужны разные инструменты, и вы хотите изолировать конфигурации.
claude mcp serve — предоставление Claude Code в качестве MCP-сервера
Направление также работает в обратную сторону. claude mcp serve запускает сам Claude Code как MCP-сервер, позволяя другому MCP-хосту подключиться к нему и использовать его инструменты:
claude mcp serve
Это полезно, если вы хотите встроить возможности Claude Code в более крупный конвейер агентов, где другой хост управляет вызовами инструментов.
Конфигурация MCP-серверов в Claude Desktop
Claude Desktop хранит конфигурацию MCP-серверов в JSON-файле. Расположение зависит от вашей операционной системы:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Если файл не существует, создайте его. Структура выглядит следующим образом:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key_here"
}
}
}
}
Каждый ключ внутри mcpServers — это имя сервера, которое Claude будет использовать для его идентификации. Вы можете зарегистрировать столько серверов, сколько нужно — Claude Desktop загружает их все при запуске.
После редактирования файла перезапустите Claude Desktop, чтобы изменения вступили в силу. Вы увидите значок молотка в области ввода чата, когда MCP-инструменты будут успешно загружены.
Добавление удаленного MCP-сервера через SSE
Для удаленных серверов, использующих транспорт Server-Sent Events (SSE) вместо stdio, структура конфигурации немного отличается:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
Некоторые удаленные серверы требуют аутентификации. Передайте bearer-токен в поле headers, если сервер этого ожидает:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse",
"headers": {
"Authorization": "Bearer your_token_here"
}
}
}
}
Типы MCP-транспорта: stdio vs SSE
MCP-серверы взаимодействуют с хостом Claude через один из двух транспортных механизмов:
stdio — Сервер запускается как подпроцесс на той же машине. Хост запускает процесс и читает/записывает JSON-RPC сообщения через стандартный ввод/вывод. Это стандартный режим для локальных серверов и самый простой в настройке.
SSE (Server-Sent Events) — Сервер работает удаленно и предоставляет HTTP-конечную точку. Хост подключается к URL и получает ответы инструментов в виде потока. Это работает между машинами и является правильным выбором для общей командной инфраструктуры или размещенных сервисов инструментов.
Для большинства индивидуальных разработчиков, начинающих работу, stdio проще — не требует сетевого взаимодействия, и процесс сервера управляется автоматически. SSE становится ценным, когда вы хотите, чтобы команда использовала один MCP-сервер, или когда сам инструмент должен работать в определенной сетевой среде.
Как Claude принимает решения об MCP-инструментах
Когда сессия начинается и MCP-серверы зарегистрированы, Claude запрашивает у каждого сервера список доступных инструментов. Это создает список имен инструментов и описаний в формате JSON Schema. Claude не вызывает инструменты в спекулятивном режиме — он вызывает инструмент только тогда, когда этого требует разговор или задача, основываясь на описании того, что делает инструмент.
Поток вызова инструмента работает следующим образом:
- Пользователь отправляет сообщение или задачу.
- Claude оценивает, может ли какой-либо зарегистрированный инструмент помочь.
- Если да, Claude формирует вызов инструмента с соответствующими аргументами.
- MCP-хост отправляет вызов соответствующему серверу.
- Сервер выполняет команду и возвращает результат.
- Claude использует результат в своих рассуждениях и продолжает.
Этот цикл может выполняться несколько раз за один шаг — Claude может объединять вызовы инструментов, использовать результаты одного инструмента для формирования аргументов другого и агрегировать данные с нескольких серверов в одной сессии.
Качество описаний инструментов имеет большое значение. Расплывчатые описания приводят к пропущенным или неверным вызовам. Точные описания, включающие то, что делает инструмент, что означают его аргументы и что он возвращает, позволяют Claude точно направлять вызовы без догадок.
Выполнение инструментов в изолированной среде (песочнице)
Когда MCP-инструменты выполняют код — Python-скрипты, команды оболочки, файловые операции — их запуск на локальной машине поднимает вопросы изоляции. Инструмент с доступом к файловой системе, порождением процессов или сетевыми вызовами имеет широкий охват, если он ведет себя некорректно или получает команду на неожиданное действие.
Novita AI Agent Sandbox решает эту проблему, предоставляя изолированные облачные среды для выполнения инструментов. Вместо запуска MCP-сервера локально, вы разворачиваете его внутри экземпляра песочницы. Песочница получает собственную файловую систему, сетевой контур и ограничения ресурсов. Агент может записывать файлы, запускать код и вызывать внутренние API внутри этой границы, не затрагивая хост-машину.
MCP-сервер, работающий внутри песочницы, предоставляет свои инструменты через SSE-транспорт, и Claude подключается к нему удаленно — так что с точки зрения Claude интеграция идентична. Разница заключается исключительно в том, на чём на самом деле выполняется инструмент.
Ключевые характеристики Novita Sandbox для развертывания MCP:
- Быстрый запуск: экземпляры запускаются менее чем за ~200 мс, что обеспечивает низкую задержку при往返 вызовах инструментов
- Посекундная оплата: вы платите только за активное время выполнения, а не за простой
- Изолированная файловая система: каждый экземпляр песочницы имеет отдельное рабочее пространство, что предотвращает утечку данных между сессиями
- Настраиваемая сетевая политика: управляйте тем, к каким внешним сервисам может обращаться инструмент
Пошаговое руководство по созданию MCP-сервера на базе Novita Sandbox см. в статье Создание MCP-сервера для удаленного выполнения кода с помощью Novita Sandbox и библиотеки mcp-use.
Использование Novita LLM API для принятия решений об MCP-инструментах
Хотя собственные модели Claude изначально поддерживают работу с инструментами, вы можете захотеть направить часть логики принятия решений об MCP-инструментах через другую модель — по соображениям стоимости, задержки или специализации. Novita LLM API предоставляет конечную точку, совместимую с OpenAI, с доступом к моделям, поддерживающим вызов функций и структурированный вызов инструментов.
Это вписывается в архитектуры MCP двумя способами:
1. В качестве модели принятия решений для пользовательского MCP-хоста: Если вы создаете свой собственный MCP-хост (вместо использования Claude Code или Claude Desktop), вы можете использовать Novita LLM API для работы модельного уровня. Хост вызывает Novita API со списком инструментов и диалогом; модель возвращает инструкции по вызову инструментов; хост отправляет их на MCP-сервер.
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="your_novita_api_key",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "Перечисли доступные инструменты и запусти быстрый тест"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "Перечислить все доступные модели из API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. В качестве LLM внутри самого MCP-инструмента: MCP-инструмент может использовать Novita LLM API внутренне — например, инструмент для суммаризации, классификации или генерации кода. Инструмент принимает входные данные от агента, вызывает Novita API и возвращает результат. Это позволяет разделить затраты на вывод модели и затраты на основную модель агента и выбрать подходящую модель для каждой подзадачи.
Практический пример создания MCP-сервера, вызывающего Novita API, см. в статье Как создать свой первый MCP-сервер с помощью Novita AI.
Часто встречающиеся проблемы и их решения
Сервер не отображается в Claude Desktop
Наиболее частая причина — синтаксическая ошибка JSON в файле claude_desktop_config.json. Используйте валидатор JSON перед сохранением. Даже лишняя запятая помешает загрузке файла. Перезапускайте Claude Desktop после каждого редактирования.
Команда claude mcp add не найдена
Это означает, что Claude Code либо не установлен, либо не находится в вашем PATH. Установите Claude Code через npm install -g @anthropic-ai/claude-code и проверьте с помощью claude --version.
Инструменты перечислены, но никогда не вызываются
Claude вызывает инструмент только тогда, когда считает его релевантным текущей задаче. Если ваши описания инструментов слишком расплывчаты, Claude не будет их выбирать. Добавьте конкретику: что делает инструмент, когда его использовать, какие у него входные и выходные данные.
Сервер завершает работу сразу после запуска
Проверьте, что команда сервера верна и все необходимые переменные окружения установлены. Запустите команду напрямую в терминале, чтобы увидеть фактический вывод ошибок — в некоторых конфигурациях Claude Code может подавлять stderr подпроцесса.
SSE-соединение отклонено
Убедитесь, что URL сервера доступен с машины, на которой запущен Claude, что сервер действительно прослушивает ожидаемый порт и что все необходимые заголовки аутентификации настроены правильно.
Вызовы инструментов завершаются ошибками валидации
Аргументы, передаваемые Claude, должны соответствовать JSON Schema, объявленной инструментом. Проверьте определение inputSchema вашего инструмента — если обязательные поля отсутствуют или типы не совпадают, сервер отклонит вызов. Claude формирует аргументы на основе схемы, поэтому неполная схема приводит к неполным вызовам.
Часто задаваемые вопросы (FAQ)
Поддерживает ли Claude Code MCP?
Да. Claude Code имеет встроенную поддержку MCP через подкоманду claude mcp. Используйте claude mcp add для регистрации серверов, claude mcp list для просмотра зарегистрированных и claude mcp remove для удаления. Выполните claude mcp --help для получения полной справки по командам.
Как добавить MCP-сервер в Claude Code?
Выполните claude mcp add <имя> <команда> [аргументы...] для stdio-сервера или используйте --json для передачи JSON-спецификации. Для регистрации в рамках проекта добавьте --scope project. После добавления начните новую сессию Claude Code — инструменты будут доступны немедленно.
Что такое claude mcp serve?
claude mcp serve запускает Claude Code в качестве MCP-сервера, предоставляя его возможности через протокол MCP. Другой MCP-хост может затем подключиться к Claude Code и использовать его как источник инструментов. Это полезно при создании мультиагентных систем, где Claude является одним из нескольких компонентов.
Можно ли использовать один и тот же MCP-сервер в Claude Code и Claude Desktop?
Да. Серверу всё равно, какой хост к нему подключается. Для stdio-серверов как Claude Code (через claude mcp add), так и Claude Desktop (через claude_desktop_config.json) могут запускать одну и ту же команду. Для SSE-серверов любой хост, имеющий доступ к URL, может подключиться.
Откуда Claude знает, какой MCP-инструмент вызвать?
В начале сессии Claude запрашивает у всех зарегистрированных серверов списки их инструментов. Каждый инструмент имеет имя и описание. При обработке задачи Claude выбирает инструменты на основе того, соответствуют ли их описания требуемому. Хорошо написанные описания с четкими вариантами использования приводят к точному выбору инструментов; расплывчатые описания приводят к пропущенным или неверным вызовам.
Есть ли ограничение на количество MCP-серверов, которые я могу зарегистрировать?
Спецификация MCP не устанавливает жестких ограничений, как и Claude Code или Claude Desktop. На практике наличие десятков серверов с сотнями инструментов может замедлить запуск сессии (обнаружение инструментов происходит при запуске) и может добавить шума при выборе инструментов Claude. Старайтесь, чтобы набор инструментов был сфокусирован на том, что действительно нужно для данного проекта или сессии.
В чем разница между транспортами stdio и SSE?
Stdio запускает сервер как локальный подпроцесс; хост взаимодействует через stdin/stdout. SSE подключается к удаленной HTTP-конечной точке и получает ответы в виде потока. Stdio проще для локальной разработки; SSE лучше подходит для удаленных, общих или производственных развертываний.
