Подключить MCP к Claude / Cursor

MCP (Model Context Protocol) — открытый стандарт: подключаешь «сервер-инструмент», и ИИ может им пользоваться (читать файлы, открывать браузер, ходить в БД, тянуть доки). Конфиг у разных клиентов почти одинаковый — объект mcpServers с полями command / args / env. Команды сверены с офиц. документацией Claude Code.

🧭 Картина целиком

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

Что получишь на выходе: ИИ, который сам читает/правит файлы проекта (Filesystem), подтягивает актуальные доки библиотек (Context7), открывает браузер и проверяет веб-флоу (Playwright), работает с репозиторием и PR (GitHub), ходит в БД (Postgres, лучше read-only).

Ключевая идея — один формат для всех. Что Claude Code, что Claude Desktop, что Cursor — везде сервер описывается одинаково: чем его запустить (command), с какими аргументами (args) и какими секретами в окружении (env). Понял один раз — подключишь к любому клиенту.

💡 Большинство серверов запускаются через npx (нужен Node.js LTS — nodejs.org) или docker (нужен Docker). Поставь хотя бы Node заранее.

Шаг 1. Claude Code (CLI) — самый быстрый путь

Что делаем: добавляем сервер одной командой claude mcp add. Важно: все флаги идут ДО имени сервера, затем -- отделяет команду самого сервера.

# локальный stdio-сервер (через npx):
claude mcp add --transport stdio playwright -- npx -y @playwright/mcp@latest
claude mcp add --transport stdio context7 -- npx -y @upstash/context7-mcp

# удалённый HTTP-сервер (рекомендуемый транспорт для облачных):
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# с переменной окружения (секрет/ключ) — флаг --env ДО имени:
claude mcp add --transport stdio --env AIRTABLE_API_KEY=ВАШ_КЛЮЧ airtable -- npx -y airtable-mcp-server

Управление и проверка:

claude mcp list            # список серверов и статус
claude mcp get context7    # детали одного сервера
claude mcp remove context7 # удалить

Как понять, что ОК: claude mcp list показывает сервер со статусом «connected» (зелёный). Внутри Claude Code набери /mcp — увидишь сервер и число его инструментов. Для облачных серверов через /mcp проходит OAuth-вход в браузере.

Область видимости (--scope, флаг ставится ДО имени):

• --scope local (по умолчанию) — только этот проект, приватно (хранится в ~/.claude.json).
• --scope project — общий для команды, пишется в .mcp.json в корне репозитория (коммитится в git).
• --scope user — во всех твоих проектах.

Частые ошибки:

• Перепутал порядок — claude mcp add playwright --transport stdio -- ... не сработает. Флаги (--transport, --env, --scope, --header) — строго ДО имени, -- — перед командой сервера.
• command not found: claude — не установлен Claude Code CLI. Поставь его, проверь claude --version.
• npx не находится → нет Node.js. Поставь Node LTS.
• Проектный сервер из .mcp.json висит как ⏸ Pending approval — запусти claude интерактивно и подтверди (так защищаются от чужих серверов в репо).

Шаг 2. Claude Desktop — через файл конфига

Что делаем: правим JSON-файл (Settings → Developer → Edit Config, либо напрямую).

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/ты/Desktop", "/Users/ты/Projects"]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Как понять, что ОК: после перезапуска в окне чата появляется значок инструментов/«молоток», сервер виден в настройках. Попроси «прочитай файлы в папке X» — Claude реально их перечислит.

Частые ошибки:

• Не перезапустил полностью. Нужен именно Quit (Cmd+Q / выход из трея), а не закрытие окна — иначе сервер не подхватится.
• Сломанный JSON (лишняя/пропущенная запятая) → конфиг не читается, серверов нет. Проверь валидатором JSON.
• На Windows путь в args с одиночными \ ломается — в JSON экранируй как \\ или используй /.

Шаг 3. Cursor — тот же формат, свой файл

Что делаем: кладём такой же mcpServers-JSON в файл Cursor.

• Проект: .cursor/mcp.json в корне репозитория. Глобально: ~/.cursor/mcp.json.
• Структура та же — command / args / env. Если сервер задан и в проекте, и глобально — побеждает проектный.

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<ВАШ_ТОКЕН>" }
    }
  }
}

Как понять, что ОК: в Settings → MCP сервер горит зелёным, инструменты появились в списке. Агент в Cursor может ими пользоваться.

Частые ошибки:

• Сервер серый/не стартует — не установлен Docker/Node, или опечатка в args.
• «Потолок» инструментов: у Cursor ограничение на число активных тулзов сразу со всех MCP. Подключишь лишнее — часть инструментов молча отвалится. Держи только нужные серверы.

Шаг 4. Базовый набор серверов «на старте»

• Filesystem — файлы проекта (читать/писать).
• Context7 — актуальные доки библиотек (меньше «галлюцинаций» по API).
• Playwright — браузер/тесты (проверить, что веб-флоу реально работает).
• GitHub — репозитории/PR/issues.
• Postgres — БД (давай read-only доступ).

Как понять, что ОК: этих 3–5 серверов хватает на 90% задач разработки; не гонись за количеством — больше серверов = больше шума и риска.

🧠 Для сеньора

• Транспорты: http (он же streamable-http) — рекомендуемый для облачных; SSE — deprecated, не выбирай для нового. Для серверов, которые пушат события, есть WebSocket (ws) — только через claude mcp add-json.
• JSON-импорт: claude mcp add-json <name> "{...}" — добавить сервер целиком из JSON (удобно копировать из доки сервера); claude mcp add-from-claude-desktop — импорт из Desktop.
• Переменные в .mcp.json: поддерживаются ${VAR} и ${VAR:-default} в command/args/env/url/headers — шаришь конфиг команде, секреты подставляются из окружения каждого.
• OAuth: /mcp запускает поток; для серверов без Dynamic Client Registration — --client-id/--client-secret/--callback-port. Токены лежат в keychain, не в конфиге.
• Tool Search: в Claude Code по умолчанию тулзы MCP подгружаются лениво (ENABLE_TOOL_SEARCH) — можно держать много серверов без раздувания контекста; критичные пометь alwaysLoad: true.
• Scope-гигиена: командные серверы — --scope project (.mcp.json в git, но БЕЗ секретов в нём); личные с ключами — local/user.

⚠️ Предупреждения (безопасность)

• MCP-сервер выполняет код и ходит в сеть. Ставь только те, которым доверяешь (supply-chain): сверяй издателя пакета/образа, не запускай случайные серверы из интернета. Это буквально даёт стороннему коду доступ к твоей машине.
• Prompt-injection. Сервер, тянущий внешний контент (веб, письма, тикеты), может принести спрятанную инструкцию «удали…/слей секреты…». Не давай агенту выполнять такое вслепую; держи подтверждения опасных действий.
• Секреты — в env/keychain, не в коде и не в общем .mcp.json. Для БД — минимальные права (read-only), чтобы агент не мог что-то снести.
• Проектный .mcp.json требует подтверждения — не подтверждай не глядя серверы из чужого/склонированного репозитория.

🆘 Промт-спасалка

Помоги подключить MCP-сервер, объясняй по шагам.
СЕРВЕР: <название, напр. Filesystem / Context7 / Playwright / GitHub / Postgres>.
КЛИЕНТ: <Claude Code / Claude Desktop / Cursor>. МОЯ ОС: <macOS / Windows>.
Я ЗАСТРЯЛ: <сервер не виден / ошибка / не знаю, куда писать конфиг>.

Что делать:
1) Дай точную команду `claude mcp add` ИЛИ готовый JSON для конфига с ПРАВИЛЬНЫМ путём файла под мою ОС.
2) Объясни поля command/args/env простыми словами.
3) Как проверить, что сервер виден (`claude mcp list` / `/mcp` / значок в клиенте).
4) Предупреди про безопасность: доверие к серверу, секреты в env, read-only для БД.

💎 Глубина и ценность

• MCP превращает «болталку» в работника. Разница между «ИИ, который советует» и «ИИ, который делает» — это и есть MCP. Один раз дав агенту руки, ты перестаёшь копировать данные туда-сюда — он работает в твоей среде сам.
• Один стандарт — вся экосистема. MCP стал общим протоколом: сотни готовых серверов (GitHub, Sentry, Figma, БД, браузер) подключаются единообразно. Освоив формат command/args/env, ты открываешь весь этот арсенал сразу.
• Это фундамент агентов и автономии. Вайб-кодинг, авто-тесты в браузере, команда ИИ-агентов (Laskoff OS) — всё стоит на MCP. Понимание, как безопасно дать ИИ инструменты, — ключевой навык, отделяющий «игрался с чат-ботом» от «построил себе автономную команду».