Как подключить MCP-сервер к Cursor и Claude Code

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

Что такое MCP вообще - в отдельной статье: что такое MCP-сервер и зачем он нужен.

Два типа серверов

Прежде чем править конфиги, посмотрите, что вам дали.

Локальный сервер (stdio). Запускается у вас на машине как обычный процесс, общается с клиентом через стандартный ввод-вывод. В конфиге вы указываете команду запуска - обычно npx или путь к исполняемому файлу.

Удалённый сервер (HTTP). Работает на чужой машине, вы указываете адрес. Обычно требует авторизации - через OAuth в браузере или через токен.

Первый вариант не требует интернета и подходит для работы с локальными файлами. Второй нужен, когда сервер управляет чем-то внешним - облаком, базой, деплоем.

Claude Code

Самый короткий путь - команда:

claude mcp add имя-сервера -- npx -y пакет-сервера

Для удалённого сервера:

claude mcp add --transport http имя-сервера https://mcp.example.com/mcp

Проверить, что получилось:

claude mcp list

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

{
  "mcpServers": {
    "имя-сервера": {
      "command": "npx",
      "args": ["-y", "пакет-сервера"],
      "env": {
        "API_TOKEN": "${API_TOKEN}"
      }
    }
  }
}

Подстановка ${API_TOKEN} берёт значение из переменных окружения. Так токен не попадает в репозиторий - а он туда попадёт, если написать его строкой, и это самая частая ошибка при настройке.

Cursor

Cursor читает два файла:

• .cursor/mcp.json в корне проекта - сервер работает только в этом проекте.
• ~/.cursor/mcp.json в домашней папке - сервер работает везде.

Формат тот же:

{
  "mcpServers": {
    "имя-сервера": {
      "command": "npx",
      "args": ["-y", "пакет-сервера"]
    }
  }
}

Для удалённого сервера вместо command указывается url:

{
  "mcpServers": {
    "имя-сервера": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

После правки откройте настройки Cursor, раздел MCP, и убедитесь, что сервер в списке и рядом с ним зелёный индикатор. Красный - смотрите раздел про ошибки ниже.

Проверка

Не полагайтесь на индикатор в интерфейсе - он говорит только о том, что процесс запустился. Спросите агента прямо:

Какие MCP-инструменты тебе сейчас доступны?

Агент перечислит их по именам. Если в списке нет того, что вы подключали, - сервер запустился, но инструменты не объявил, и это уже проблема сервера, а не конфига.

Когда не работает

Агент не видит инструменты, хотя конфиг правильный. Клиент читает конфиг при старте. Перезапустите его полностью - не окно, а приложение.

Красный индикатор, сервер не стартует. Запустите ту же команду руками в терминале - ту, что стоит в command и args. Обычно оказывается, что npx не находит пакет или в системе нет Node.js.

Работает в терминале, но не в редакторе. Классика: редактор запускается не из вашей оболочки и не видит переменные окружения из .zshrc или .bashrc. Пропишите нужное явно в блоке env конфига.

Инструменты видны, но агент их не вызывает. Не техническая проблема, а языковая. Модель выбирает инструмент по его описанию. Скажите прямо: «используй инструмент deploy_project, чтобы задеплоить проект» - и посмотрите, вызовется ли он. Если да, дело в описаниях сервера, и это к его авторам.

Всё сломалось после обновления клиента. Формат конфигов ещё меняется. Сверьтесь с документацией вашего клиента - за последний год он менялся у всех.

Что стоит сделать до подключения

Серверы MCP - это чужой код, который получает доступ к вашим файлам, токенам и инфраструктуре. Ровно как расширения браузера.

Минимум, который стоит проверить:

• Список инструментов. Что сервер вообще умеет делать.
• Что он делает без подтверждения. Читать - нормально. Удалять и тратить деньги без спроса - нет.
• Откуда пакет. Официальный реестр или репозиторий автора, а не случайная ссылка.
• Область токена. Права на один проект лучше, чем права на весь аккаунт.

Коротко

• Claude Code: claude mcp add, либо .mcp.json в корне проекта.
• Cursor: .cursor/mcp.json в проекте или ~/.cursor/mcp.json глобально.
• После правки конфига перезапускайте клиент целиком.
• Проверка - спросить у агента список доступных инструментов.
• Токены держите в переменных окружения, а не строкой в конфиге.