- Что MCP делает в Claude
- Добавление MCP-серверов в Claude Code
- Конфигурация MCP-серверов в Claude Desktop
- Типы транспорта MCP: stdio vs SSE
- Как Claude рассуждает об инструментах MCP
- Выполнение инструментов в песочнице
- Использование Novita LLM API для рассуждений об использовании инструментов MCP
- Частые проблемы и их решения
- FAQ
- Рекомендуемые статьи
Claude изначально поддерживает Model Context Protocol (MCP), позволяя подключать внешние инструменты — базы данных, раннеры кода, API и пользовательские серверы — непосредственно в ваш рабочий процесс. Независимо от того, используете ли вы Claude Code в терминале или Claude Desktop на вашем компьютере, конфигурация MCP работает одинаково на уровне протокола, с небольшими различиями в том, как вы регистрируете серверы. Это руководство охватывает оба пути: команды CLI claude mcp add для Claude Code и файл JSON-конфигурации для Claude Desktop, а также то, как рассуждения об использовании инструментов и выполнение в песочнице вписываются в общую картину.
Что MCP делает в Claude
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 <name> <command> [args...]
Например, чтобы добавить локальный 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
Область действия: проект vs пользователь
По умолчанию 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 смотрите в Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library.
Использование 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": "List the available tools and run a quick test"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "List all available models from the API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. Как LLM внутри самого MCP-инструмента: MCP-инструмент может использовать Novita LLM API внутренне — например, инструмент для суммаризации, классификации или генерации кода. Инструмент принимает входные данные от агента, вызывает Novita API и возвращает результат. Это отделяет затраты на вывод модели от затрат основной модели агента и позволяет выбирать подходящую модель для каждой подзадачи.
Практический пример создания MCP-сервера, вызывающего API Novita, смотрите в How to Build Your First MCP Server with 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 <name> <command> [args...] для 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 лучше подходит для удалённых, общих или производственных развёртываний.
