MCP на русском: подключаем серверы к агенту за 10 минут

Коротко: MCP-сервер — это процесс, который отдаёт агенту инструменты по стандартному протоколу. Подключение сводится к одному конфигу: для stdio-сервера — команда запуска, для HTTP — URL и токен. Ниже: где брать серверы, готовые конфиги для Claude Code и Cursor, проверка работы и шесть типичных ошибок.

Что понадобится

• Клиент с поддержкой MCP: Claude Code, Claude Desktop, Cursor, Windsurf или VS Code
• Для stdio-серверов — Node.js (npx) или Python (uvx) в PATH
• 10 минут

Шаг 1. Найти сервер

Официальный реестр — registry.modelcontextprotocol.io (в превью с сентября 2025); шире по выбору — community-подборка awesome-mcp-servers. В описании каждого сервера указан транспорт: stdio (запускается командой на вашей машине) или HTTP (уже где-то работает, нужны URL и, обычно, токен).

Для примера возьмём два: filesystem — эталонный stdio-сервер из монорепо modelcontextprotocol/servers, и наш MaxGraph — сервер памяти по streamable HTTP. Если хочется сначала понять, что такое MCP вообще, — есть гайд простыми словами.

Прежде чем ставить найденное, потратьте минуту на проверку. Сервер — это код, который будет исполняться на вашей машине или получит ваши токены, поэтому смотрим на четыре вещи: кто автор (официальные серверы modelcontextprotocol и вендоров вне подозрений), звёзды и дата последнего коммита, какие права просит сервер (filesystem-серверу не нужен доступ в сеть), и есть ли исходники. Пять минут здесь экономят часы потом.

Шаг 2. Подключить в Claude Code

Для stdio-сервера — одна команда:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /путь/к/папке

Для HTTP-сервера:

claude mcp add --transport http maxgraph http://localhost:8787/mcp \
  --header "Authorization: Bearer ВАШ_ТОКЕН"

То же самое файлом — .mcp.json в корне проекта:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/путь/к/папке"]
    },
    "maxgraph": {
      "type": "http",
      "url": "http://localhost:8787/mcp",
      "headers": { "Authorization": "Bearer ВАШ_ТОКЕН" }
    }
  }
}

Файл в проекте удобен тем, что коммитится вместе с кодом (токены, разумеется, туда не кладём — переменные окружения или локальный пользовательский конфиг).

У команды claude mcp add есть флаг --scope: local — только вы и только этот проект, project — конфиг в репозитории для всей команды, user — все ваши проекты сразу. Память проекта логично держать в project, личные эксперименты — в local.

Шаг 3. Подключить в Cursor

Cursor читает ~/.cursor/mcp.json (глобально) или .cursor/mcp.json в проекте. Формат тот же самый: mcpServers, у stdio-сервера — command и args, у HTTP — url. После сохранения откройте Settings → MCP: там список серверов и их статус. Зелёный индикатор значит, что сервер поднялся и отдал клиенту список инструментов.

Нюанс Cursor: сервер может быть зелёным, но его инструменты всё равно недоступны в чате, если в настройках агента отключено автоматическое применение инструментов. Проверьте, что в настройках агента разрешены tool calls, — иначе агент будет «знать» про инструменты, но не звать их.

Шаг 4. Проверить

В Claude Code слэш-команда /mcp показывает серверы и их состояние. Универсальная проверка в любом клиенте — спросить агента: «какие MCP-инструменты у тебя есть?» Он должен перечислить инструменты подключённых серверов.

Финальный тест — попросить сделать что-то через инструмент. Например: «запомни факт: деплой у нас только через preflight-скрипт». Если агент вызвал инструмент записи и подтвердил — всё работает.

Для HTTP-сервера проверить можно и без агента, голым HTTP. У MaxGraph, например, есть эндпоинт здоровья:

curl http://localhost:8787/healthz
# → ok

Если эндпоинт отвечает, а клиент сервер не видит — проблема почти наверняка в конфиге клиента: опечатка в URL, лишний слэш в конце пути или забытый заголовок авторизации.

Шесть типичных ошибок

1. «npx: command not found», хотя Node установлен. GUI-приложения на macOS и Windows не видят PATH из вашего shell. Лечится абсолютным путём: /usr/local/bin/npx или C:\Program Files\nodejs\npx.cmd.
2. Windows и npx. Части клиентов на Windows нужна обёртка: "command": "cmd", "args": ["/c", "npx", "-y", "…"].
3. Клиент не перезапущен. Конфиг подхватывается на старте; горячей перезагрузки у большинства клиентов нет.
4. Висячая запятая в JSON. .mcp.json — строгий JSON: без комментариев и хвостовых запятых.
5. Секрет в аргументах. Токен в args попадает в список процессов и логи. Кладите секреты в env или headers.
6. Сервер есть, инструментов нет. Смотрите stderr сервера и логи клиента: в Claude Code это claude --debug, в Cursor — панель Output → MCP.

Сколько серверов — не перебор?

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

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

FAQ

Как отключить сервер? В Claude Code: claude mcp remove <имя>. В Cursor — удалить блок из mcp.json и перезапустить. Данные, которые сервер успел сохранить (у MaxGraph — граф в data/), при этом никуда не деваются.

Сервера нет в реестре — что делать? Реестр не обязателен: подходит любой исполняемый файл или URL. Локальный сервер из соседней папки подключается точно так же.

Можно ли один сервер на всю команду? Да, через streamable HTTP: поднимаете один инстанс и раздаёте URL и токены. Так устроен self-hosted сценарий MaxGraph — сервер в Docker, у каждого свой токен.

Откуда агент узнаёт, когда каким инструментом пользоваться? Из описаний инструментов и из ваших инструкций. Первое даёт сервер, второе — вы: блок правил в CLAUDE.md или .cursor/rules («когда писать в память», «что считать решением») решает больше, чем красота описаний. Рабочий пример такого блока — в статье про память для Claude Code.

Что дальше

• Теория под этой практикой: MCP простыми словами.
• Боевой сценарий от начала до конца: память для Claude Code за 10 минут.