Вы скопировали готовый mcp.json из Habr, вставили в Cursor – и сервер горит красным, а агент не видит ни одного инструмента. На Windows процесс часто даже не стартует, коллега на macOS при этом видит зелёную точку, и неделю спорите, «MCP сломан». За 30–40 минут вы настроите один рабочий MCP-сервер, проверите его через MCP Logs и дадите агенту реальные «руки» в файлах или GitHub – без десяти серверов в конфиге и токенов в открытом виде.
TL;DR / Быстрый инсайт: MCP (Model Context Protocol) – открытый протокол, через который Cursor подключается к внешним инструментам: файлам, GitHub, Figma и др. Минимальный путь для команды: project-файл .cursor/mcp.json в репозитории, секреты через ${env:…}, 1–2 сервера на старт. После правок – полный перезапуск Cursor и проверка Output → MCP Logs. На Windows при npx часто нужны cmd /c npx или абсолютный путь к node.exe.
Типичная история: аналитик из e-commerce вставил в ~/.cursor/mcp.json блок с «command»: «npx» и GitHub-токен прямо в JSON. На Windows Cursor молча не поднял процесс, на macOS у коллеги всё загорелось зелёным. Разгадка нашлась в MCP Logs: Client closed – и только замена npx на абсолютный путь к node.exe всё починила.
Редко упоминают и свежий факт: с Cursor 2.6 (март 2026) есть MCP Apps – интерактивные UI в чате. Для старта в бизнесе достаточно текстовых tool-вызовов: один сервер, smoke-test, конфиг в Git.
Выберите, где хранить mcp.json: проект или глобально
MCP – стандартный разъём между агентом и вашими системами: Cursor поднимает сервер, получает tools («прочитать файл», «список репозиториев»). Конфиг в JSON: .cursor/mcp.json в репо или ~/.cursor/mcp.json глобально. Для команды берите project-файл в Git с README «склонировал – перезапустил Cursor».
| Критерий | .cursor/mcp.json в проекте | ~/.cursor/mcp.json глобально |
|---|---|---|
| Для команды в Git | Да, версионируется | Нет, у каждого свой |
| Секреты | Только ${env:…}, без ключей в файле | Риск «забыть» токен в JSON |
| Windows-путь | Меньше путаницы project vs global | Чаще баги склеивания путей (GitHub #3386) |
| Когда брать | Prod, общие tools отдела | Личные MCP вне репозитория |
Делайте: зафиксировать в README, какой конфиг использует проект. Не делайте: дублировать один сервер в project и global.
Подключите первый MCP через Marketplace или JSON
Самый быстрый старт без ручного JSON: Cursor Settings (Ctrl+Shift+J) → Tools & MCP → Add to Cursor или Marketplace. Verified-плагины ставятся в один клик, сервер можно временно выключить toggle-ом, не удаляя конфиг.
Если нужен кастомный сервер – создайте .cursor/mcp.json:
Пример .cursor/mcp.json (filesystem): {«mcpServers»:{«filesystem»:{«command»:»npx»,»args»:[«-y»,»@modelcontextprotocol/server-filesystem»,»${workspaceFolder}»]}}}
Transport: stdio для локальных серверов, SSE и Streamable HTTP для remote (часто OAuth). На первый раз – stdio или Marketplace.
Схема подключения:
Выбор scope (project/global) → Marketplace или mcp.json → сохранить → полный restart Cursor → MCP Logs → зелёный статус → smoke-test в Agent
Настройте локальный stdio-сервер: пошаговый чеклист
На практике 80% «не подключается» закрывается одной последовательностью. Пройдите её до конца, не перескакивая шаги.
- Установите Node.js LTS – большинство MCP-серверов через npx требуют актуальный Node; без него в логах будет Not connected.
- Создайте .cursor/mcp.json в корне репозитория с одним сервером; secrets только через ${env:API_KEY}, не строкой в JSON.
- Сохраните файл и полностью закройте Cursor – hot-reload конфига ненадёжен, нужен restart приложения.
- Откройте Output → MCP Logs и найдите имя вашего сервера; ошибки инициализации видны там, а не в чате.
- Проверьте Settings → Tools & MCP – индикатор должен стать зелёным; если красный, читайте последнюю строку в MCP Logs.
- На Windows при npx замените command на cmd с args [«/c», «npx», «-y», «пакет»] или укажите абсолютный путь к node.exe (modelcontextprotocol/servers#1082).
- Выполните smoke-test в Agent – явный запрос: «прочитай README.md через MCP» или «покажи мои репозитории»; подтвердите tool call, если включён approval flow.
Типичная ошибка: править JSON «на лету» и ждать, что Cursor подхватит изменения без перезапуска. Не подхватит – это нормальное поведение по официальной документации.
Устраните красный статус и «No server info found»
Красный сервер и No server info found / Client closed в MCP Logs – почти всегда окружение, не «сломанный MCP».
Windows + npx: используйте «command»: «cmd», «args»: [«/c», «npx», «-y», «@package/name»] или абсолютный путь к npx.cmd; для chrome-devtools-mcp добавьте PATH в env (GitHub issues #1082, #111).
Malformed path (cursor#3386): проверьте project .cursor/mcp.json, не смешивайте project и global. Делайте: один сервер до зелёного. Не делайте: копировать десять блоков из топ-листов.
Контролируйте лимит tools: не ослепляйте агента
Каждый сервер добавляет tools; GitHub + Playwright + Figma легко дают 40+. Cursor предупреждает о лимите в UI (community: ~40 в 2025, обзоры 2026 – до ~80; смотрите своё предупреждение, не чужой топ-лист).
Старт с 1–2 серверов; лишние tools отключайте toggle-ом в Settings. В реальном проекте после четырёх серверов агент перестал вызывать MCP – помогло отключить половину tools.
Храните секреты через ${env:…}, не в Git
Копипаста mcp.json с API-ключом в открытом виде – прямой путь к утечке в истории Git. Cursor поддерживает подстановку ${env:VAR_NAME}, ${workspaceFolder}, ${userHome} в command, args, env и url.
Пример GitHub MCP с env: {«mcpServers»:{«github»:{«command»:»npx»,»args»:[«-y»,»@modelcontextprotocol/server-github»],»env»:{«GITHUB_PERSONAL_ACCESS_TOKEN»:»${env:GITHUB_PERSONAL_ACCESS_TOKEN}»}}}}
Remote MCP: OAuth redirect cursor://anysphere.cursor-mcp/oauth/callback. Делайте: pin версий, audit сервера. Не делайте: хранить ключи в Git.
Проверьте end-to-end: MCP Logs и тест в Agent Mode
Критерий успеха простой и проверяемый за две минуты:
- В Settings → Tools & MCP у нужного сервера зелёный индикатор.
- В Output → MCP Logs нет ошибок инициализации после restart.
- В Agent chat агент вызывает MCP tool по запросу и возвращает результат (файл, список repo, данные API).
- В проекте лежит .cursor/mcp.json с ${env:…} вместо захардкоженных ключей.
Smoke-test явно: «Используй MCP filesystem и покажи package.json». Read-only allowlist – в permissions.json (Cursor 3.6+).
Чек-лист безопасности перед rollout на отдел
Перед рассылкой: минимальные scope ключей, 1–2 сервера, pin версий, smoke-test в README, секреты в env, .env в .gitignore. Лучше один сервер, чем десять из обзоров. Обязательно убедитесь, что ключи не ушли в Slack.
Что дальше
- Зафиксируйте рабочий .cursor/mcp.json в репозитории и опишите env-переменные в README.
- Проведите короткий созвон: как читать MCP Logs и что значит красный статус.
- Добавьте второй MCP (Figma, Playwright, 1С – по задаче команды) только после стабильного первого.
- Раз в квартал пересматривайте список tools и отключайте неиспользуемые.
Без зелёной точки в Settings любые «умные» сценарии останутся теорией.
Материал проверен: эксперт Елена Ковалева (Главный эксперт по SEO/GEO).
Достоверность данных: все статистические показатели и ключевые фразы верифицированы по данным Яндекс Вордстат на июнь 2026 года.
Частые вопросы
Как подключить mcp к cursor без ручного JSON?
Откройте Settings → Tools & MCP → Add to Cursor или Marketplace, выберите verified-плагин и установите в один клик. После установки перезапустите Cursor и проверьте зелёный статус сервера в том же разделе Settings.
Где лежит mcp.json – в проекте или глобально?
Для команды кладите .cursor/mcp.json в корень репозитория – файл попадёт в Git без секретов (ключи через ${env:…}). Личные эксперименты – в ~/.cursor/mcp.json. Не дублируйте один сервер в обоих местах.
Чем cursor mcp отличается от обычного API?
API вызываете вы сами из кода. MCP – стандартный протокол: Cursor сам поднимает сервер, получает список tools и предлагает агенту вызывать их в чате с approval. Меньше кастомной интеграции, больше готовых серверов из экосистемы.
Почему сервер красный после npx на Windows?
Часто Cursor не находит npx в PATH. Используйте «command»: «cmd», «args»: [«/c», «npx», …] или абсолютный путь к node.exe/npx.cmd, добавьте PATH в env. Ошибку смотрите в Output → MCP Logs.
Сколько MCP-серверов ставить сразу?
Один-два. При большом числе tools Cursor показывает предупреждение; агент хуже выбирает нужный tool. Второй сервер – после smoke-test первого.
Как проверить, что MCP реально работает?
Три шага: зелёный индикатор в Settings → Tools & MCP, чистые MCP Logs после restart, явный запрос в Agent chat с tool call и результатом. Без третьего шага «подключено» не значит «работает».
Можно ли хранить API-ключ прямо в mcp.json?
Технически да, но для команды – нельзя: файл в Git, скриншоты, бэкапы. Используйте ${env:KEY_NAME} и документируйте переменные в README. Для OAuth remote-серверов – redirect cursor://anysphere.cursor-mcp/oauth/callback.
