Как подключить MCP-сервер: 6 шагов + 8 ошибок, из-за которых он не виден

Что получится и сколько это займёт

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

Порядок ниже одинаков для OpenClaw, Claude Code, Cursor, Codex и остальных: различается только файл, в который пишется конфигурация.

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

• Агент, который умеет MCP. Почти все умеют, но версия должна быть свежей.
• Node.js либо Python — тем, чем запускается выбранный сервер. Большинство серверов ставится через npx (Node) или uvx (Python). Если сервер размещённый, по адресу https://…, ничего ставить не нужно вовсе.
• Доступ к системе, которую подключаете: токен, ключ или учётные данные. Заводите отдельные, а не свои рабочие.
• Терминал. Одна проверка делается только в нём, и без неё вы будете чинить не то.

ВажноОтдельный доступ — не формальность. Сервер работает ровно с теми правами, которые вы ему выдали, и первое подключение почти всегда делается «чтобы просто заработало». Разграничить потом сложнее, чем сразу.

1. Выбрать сервер и проверить, что он живой

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

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

Если готового под вашу систему нет, его пишется свой — задача на вечер, а не на неделю.

2. Решить, локальный сервер или размещённый

Два способа, и выбор влияет на всё остальное.

Локальный (stdio). Сервер запускается у вас как процесс, общение идёт через стандартный ввод-вывод. Данные не покидают машину, ничего не торчит наружу. Так подключают файлы, базы и локальные инструменты.

Размещённый (HTTP). Сервер живёт по адресу, агент ходит к нему по сети. Ставить нечего, обновляется сам, но запросы проходят через чужую инфраструктуру, и появляется авторизация.

Обычно выбор делает за вас документация сервера. Развёрнуто — локальный MCP-сервер против удалённого.

3. Запустить сервер отдельно от агента

Шаг, который пропускают все и потом теряют вечер. Сервер запускается из терминала сам по себе, без всякого агента:

npx -y @modelcontextprotocol/server-filesystem ~/Документы

Правильное поведение выглядит странно: команда не завершается и ничего не печатает — сервер ждёт, когда с ним заговорят по стандартному вводу. Это и есть успех. Прерывайте по Ctrl+C и идите дальше.

А вот если вы увидели command not found, ошибку установки пакета или сообщение о правах — проблема здесь, и в конфигурации агента её чинить бесполезно.

4. Прописать сервер в конфигурации агента

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

Для локального сервера запись выглядит так:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/путь/к/папке"]
    }
  }
}

Для размещённого — адрес и заголовки:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "ваш-ключ" }
    }
  }
}

В Claude Code то же самое делается командой claude mcp add, и там же выбирается уровень: только этот проект, все ваши проекты или файл в репозитории для команды. Разбор уровней — MCP в Claude Code. Для OpenClaw порядок расписан в инструкции по подключению.

ОсторожноВ проектный файл, который уезжает в репозиторий, ключи не кладут. Там место адресам и ссылкам на переменные окружения — иначе секрет уедет вместе с историей коммитов, откуда его уже не убрать.

5. Выдать минимальные права

Здесь создают проблемы на будущее, и здесь же они дешевле всего решаются.

• Отдельный технический пользователь для агента, а не ваша учётная запись и тем более не администратор.
• Только нужные объекты. Нужны контрагенты и заказы — открывайте их, а не всю базу.
• Чтение по умолчанию. Запись включается под конкретную задачу, когда сценарий уже отработан.
• Подтверждение на изменения первое время: агент готовит, человек проводит.

Подробнее — безопасность MCP и права доступа агента.

6. Перезапустить и проверить, что сервер виден

Конфигурация читается при старте. Перезапустите агента целиком — не «новый чат», а именно приложение или процесс.

В Claude Code список подключённого показывает команда /mcp прямо в сессии. У остальных клиентов список серверов лежит в настройках либо пишется в лог при запуске.

Проверять надо в два приёма:

1. Сервер в списке и в статусе «подключён». Если его нет — дело в конфигурации, смотрите раздел с ошибками ниже.
2. Инструмент вызывается. Дайте задачу, которая без сервера невозможна: «покажи, какие файлы лежат в этой папке». Если агент ответил общими словами вместо вызова инструмента — сервер виден, но агент не понял, когда его применять.

8 ошибок, из-за которых сервер не виден

По убыванию частоты.

1. Не перезапустили клиента. Конфигурация читается на старте. Новый чат — не перезапуск.

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

3. npx или uvx не найдены. В терминале команда работает, а из приложения — нет: у приложения, запущенного из интерфейса, другой PATH. Лечится указанием полного пути к исполняемому файлу (which npx покажет его) либо запуском клиента из терминала.

4. Windows и npx. На Windows команду заворачивают в cmd: вместо "command": "npx" пишется "command": "cmd", а к аргументам спереди добавляется "/c", "npx". Записи с uvx при этом не трогают.

5. Пакет архивный или его нет. Имя вида @modelcontextprotocol/server-<название> живо только для семи референсных серверов. Остальные переехали к вендорам, и старое имя либо не ставится, либо ставит замороженную версию.

6. Ключ не подставился. В конфигурации написано ${MY_TOKEN}, а переменная объявлена в .zshrc, до которого приложение не добирается. Сервер стартует и падает на первом же запросе с ошибкой авторизации.

7. Прав не хватило. Сервер виден, инструмент вызывается, ответ — отказ. Это уже не про подключение: проверяйте, что может пользователь, под которым настроен сервер.

8. Модель не умеет инструменты. Особенно на локальных моделях: без поддержки вызова инструментов модель ответит текстом вместо вызова. Со стороны выглядит как «MCP не работает». Какие локальные модели умеют.

ПолезноПорядок диагностики всегда один: сначала запускается ли сервер сам по себе (шаг 3), потом виден ли он агенту, и только потом — вызывается ли инструмент. Три разные проблемы с тремя разными решениями, и путать их дороже всего.

Как обновить, отключить и убрать сервер

Три операции, которые понадобятся сразу после того, как первый сервер заработает.

Обновление. Запись npx -y пакет@latest тянет свежую версию при каждом старте — удобно, но означает, что рабочая конфигурация может измениться сама, без вашего участия. На боевом окружении версию имеет смысл зафиксировать явно, а обновлять руками и осознанно. На домашнем @latest обычно удобнее.

Отключение без удаления. Убирать запись из конфигурации, чтобы временно выключить сервер, — плохая идея: обратно вы её будете собирать по памяти. У большинства клиентов есть флаг отключения ("disabled": true или переключатель в интерфейсе), у части — команда. Так конфигурация остаётся на месте, а сервер не грузится.

Удаление. Кроме записи в конфигурации остаётся кэш пакета и, возможно, выданный токен. Запись убрали — отзовите и токен: доступ, о котором вы забыли, живёт ровно до того дня, когда о нём вспомнит кто-то другой.

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

Коротко о главном

• Подключение — это три вещи: чем запускать, с какими аргументами, с какими правами.
• Запустите сервер в терминале отдельно, до всякой конфигурации. Молчащая команда — это успех.
• Права по умолчанию: отдельный пользователь, только чтение, только нужные объекты.
• Перезапуск целиком, а не новый чат.
• Если сервер не виден — почти всегда это сломанный JSON, отсутствие перезапуска или PATH.

Начните с одного сервера и одного сценария. Агент с десятком подключений и без понимания, что он делает, — источник проблем, а не пользы.

Дальше: 15 рабочих серверов с разбором, особенности Claude Code и как написать свой сервер.