Как подключить MCP-сервер к ИИ-агенту: пошаговая настройка в OpenClaw

Коротко. MCP-сервер — это отдельная программа, которая отдаёт агенту готовый набор инструментов: поиск по документации, чтение файлов, вызовы вашего API. Чтобы подключить его к OpenClaw, нужны три команды, а не одна. Сохранить определение — openclaw mcp add <имя> --command npx --arg -y --arg <пакет> для локального сервера или --url https://… --transport streamable-http для удалённого. Убедиться, что сервер реально отвечает и отдаёт инструменты — openclaw mcp doctor <имя> --probe. Урезать список инструментов до тех, что вам действительно нужны — openclaw mcp tools <имя> --include 'search,read_*'. Второй и третий шаги пропускают чаще всего, и именно из них растут две типовые жалобы: «подключил, но агент ничего не видит» и «агент вызвал не то, что я ожидал». Ниже — рабочая последовательность для обоих транспортов, разбор фильтров инструментов, OAuth и то, что OpenClaw молча вырезает из окружения локального MCP-сервера ради вашей же безопасности.

На чём это проверено

Все команды, флаги, ключи конфигурации и значения по умолчанию сверены с официальной документацией проекта в репозитории github.com/openclaw/openclaw на теге v2026.9.4 — это актуальный релиз на 11 сентября 2026 года. Проект выпускает релизы часто, поэтому перед переносом в боевой конфиг сверьтесь с docs.openclaw.ai: имена команд стабильны, а набор полей в определении сервера растёт от версии к версии.

Статья предполагает, что OpenClaw уже установлен, провайдер подключён и агент отвечает. Если нет — сначала установка, потом первичная настройка, и только затем инструменты.

Что такое MCP-сервер и чем он не является

Model Context Protocol — это способ для агента «одолжить» инструменты у другой программы. MCP-сервер публикует три вида объектов: инструменты (функции, которые агент может вызвать), ресурсы (данные, которые можно прочитать) и промпты (заготовленные шаблоны запросов). OpenClaw подключается к серверу как клиент и делает его инструменты доступными вашим агентам.

Три вещи, которые важно понять до первой команды.

• Это не плагин и не расширение OpenClaw. MCP-сервер — отдельный процесс или отдельный сетевой сервис, который можно написать на чём угодно и переиспользовать с другими агентными системами. Вы не «ставите его в OpenClaw», вы сохраняете в конфиге описание того, как до него достучаться.
• Подключение сервера не обходит вашу политику инструментов. Инструменты, которые приходят из MCP, проходят через те же профили и политики, что и встроенные. Если в профиле инструментов агента MCP не разрешён, сервер будет подключён и при этом бесполезен.
• Сохранить определение и подключиться — разные события. Команды list, show, status, set, configure, tools, unset вообще не ходят в сеть. Живое соединение открывают только probe и doctor --probe. Это главный источник ложной уверенности: конфиг красивый, сервер мёртвый.

Отдельно: у OpenClaw есть и обратный режим — openclaw mcp serve, когда сам OpenClaw выступает MCP-сервером и отдаёт наружу переписку из своих каналов. Это другая задача, и в этой статье она не разбирается.

Шаг 0. Выберите транспорт

Транспорт — это способ, которым OpenClaw разговаривает с сервером. Их три, и выбор определяется не вкусом, а тем, где сервер физически живёт.

Транспорт	Когда выбирать	Обязательное поле
stdio	Сервер — локальная программа, которую запускает сам OpenClaw и общается с ней через стандартный ввод-вывод	command
sse	Удалённый сервер по HTTP Server-Sent Events. Значение по умолчанию, если transport не указан, а url есть	url
streamable-http	Удалённый сервер с двусторонним HTTP-стримингом — то, что сегодня отдаёт большинство новых публичных MCP-серверов	url

Включённому серверу нужно либо command (stdio), либо url (SSE или Streamable HTTP). Если сервер поддерживает Streamable HTTP — указывайте его явно: при пропущенном transport OpenClaw возьмёт sse, и вы получите соединение, которое формально работает, но не тем способом, которым сервер рассчитывал общаться.

Есть ещё одна мелочь, на которой легко потерять полчаса: имя __proto__ зарезервировано и сервер с таким именем создать нельзя. Имена в остальном произвольные, но короткие и без пробелов удобнее — вы будете набирать их в каждой второй команде.

Шаг 1. Локальный сервер через stdio

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

openclaw mcp add memory \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-memory

Обратите внимание на форму записи аргументов: каждый аргумент — отдельный --arg, а не одна строка через пробел. Это не украшательство, а защита от того, что аргумент с пробелами внутри развалится на два.

Для сервера, который вы написали сами, добавляются рабочая директория и переменные окружения:

openclaw mcp add local-tools \
  --command node \
  --arg ./dist/mcp-server.js \
  --cwd /srv/openclaw-tools \
  --env API_BASE=https://internal.example

Полный набор полей stdio-сервера: command (обязательное), args (массив аргументов), env (дополнительные переменные окружения) и cwd — у него есть синоним workingDirectory, оба валидны.

Команда add по умолчанию сама делает пробное подключение перед сохранением — если сервер не стартует, вы узнаете об этом сразу, а не через неделю. Отключается это флагом --no-probe; отключать имеет смысл только тогда, когда серверу для старта нужна авторизация, которой у вас ещё нет.

Здесь же стоит честно оценить, сколько времени всё это займёт. Одно подключение — пять минут. Десять серверов, у каждого свой транспорт, свой способ авторизации, свой список инструментов и своя манера ломаться после обновления — это уже отдельная инженерная работа, которую кто-то должен вести постоянно. Если держать её внутри некому, мы соберём набор инструментов агента под ваши задачи и будем поддерживать его в рабочем состоянии. Дальше по тексту — как сделать это самому.

Шаг 2. Проверка: сохранить ≠ подключить

Это шаг, который пропускают, и именно он отвечает на вопрос «почему агент не видит инструменты». Сохранённое определение не доказывает ничего о доступности сервера — доказывает только живая проверка.

openclaw mcp doctor memory --probe

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

Три родственные команды, которые полезно различать:

• openclaw mcp status --verbose — сводка по конфигу без подключения: разрешённый транспорт, способ авторизации, таймауты, фильтры, подсказки о параллельных вызовах. Показывает и то, что сохранённые OAuth-токены требуют дополнительной авторизации. Аргументы stdio, похожие на учётные данные, в выводе замаскированы.
• openclaw mcp doctor без --probe — только статические проверки, тоже без сети.
• openclaw mcp probe <имя> — чистое живое подключение: количество инструментов, поддержка ресурсов и промптов, поддержка динамического изменения списка инструментов, диагностика. Без имени проверяет все настроенные серверы сразу.

У всех трёх есть --json — если вы заворачиваете проверку в собственный мониторинг, работайте с JSON, а не парсите текст.

Шаг 3. Удалённый сервер по HTTP и OAuth

Удалённый сервер без авторизации подключается одной командой:

openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --include 'search,read_*'
openclaw mcp doctor docs --probe

Если сервер требует OAuth, порядок другой: сначала сохраняем определение с auth: "oauth", потом проходим логин.

openclaw mcp set docs '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"docs.read"}}'
openclaw mcp login docs

OpenClaw поднимает локальный callback-слушатель, печатает ссылку авторизации и сам завершает обмен токенами, когда браузер вернётся на loopback-адрес. Если браузер на другой машине или не может достучаться до напечатанного адреса — есть ручной путь: скопировать код и передать его обратно.

openclaw mcp login docs --code abc123

Дальше — ровно то же подтверждение, что и везде:

openclaw mcp status --verbose
openclaw mcp doctor docs --probe

Несколько неочевидных правил этого режима, которые экономят вечер.

• Статический заголовок Authorization игнорируется, пока включён auth: "oauth". Если вы оставили и то и другое, работать будет OAuth, а заголовок будет тихо лежать в конфиге и вводить в заблуждение.
• Токены живут в SQLite, а не в JSON. Нативные OAuth-сессии MCP хранятся в общей базе состояния <state-dir>/state/openclaw.sqlite, таблица mcp_oauth_stores. Логин, обновление и выход используют одну и ту же блокировку, поэтому два параллельных процесса OpenClaw не «съедят» один refresh-токен и не воскресят закрытую сессию.
• Отсутствие учётных данных не роняет ход агента. Пока нужных credentials нет, OpenClaw просто исключает этот сервер из рантайма — агент отработает без него. Это удобно и одновременно коварно: агент не пожалуется, он просто не сможет то, что вы от него ждали. Поэтому status --verbose и стоит смотреть глазами.
• Ошибка insufficient_scope не лечится повтором. Если сервер отвергает токен из-за нехватки прав, OpenClaw не будет бессмысленно обновлять токен, а попросит заново пройти openclaw mcp login <имя> — обновление не может выдать новые права.
• logout убирает учётные данные, но не удаляет сервер. Определение остаётся, и это правильно: вы чистите доступ, а не конфигурацию.

Отдельный режим — oauth.identity: "per-requester", когда каждый авторизованный отправитель подключает собственный аккаунт вместо общего операторского. Он требует HTTP-сервера и обязательно gateway.publicOrigin — внешне достижимого HTTPS-адреса шлюза, куда провайдер вернёт пользователя по пути /oauth/mcp/callback. У режима есть важное ограничение по безопасности, о котором документация предупреждает прямо: ссылка на вход одноразовая и предъявительская, и любой участник чата, который её откроет, привяжет свой аккаунт. Включайте его только там, где все отправители доверяют друг другу.

Шаг 4. Фильтр инструментов — обязательный шаг, а не опция

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

openclaw mcp tools docs --include 'search,read_*'
openclaw mcp tools docs --exclude 'admin_*'
openclaw mcp tools docs --clear

То же самое в конфиге:

toolFilter: {
  include: ["search_*"],
  exclude: ["admin_*"],
}

Записи — это точные имена инструментов MCP или простые глобы со звёздочкой. Фильтр применяется до того, как инструменты станут инструментами OpenClaw, то есть отфильтрованное не попадает в контекст вообще.

Важная деталь, которая ловит почти всех: если сервер объявляет ресурсы или промпты, OpenClaw дополнительно генерирует служебные инструменты с именами resources_list, resources_read, prompts_list и prompts_get. Они подчиняются тому же фильтру. Из этого следует практическое правило: узкий include может случайно отрезать служебные инструменты, и агент вдруг перестанет видеть ресурсы сервера, хотя сам сервер жив и здоров. Если после включения фильтра пропало что-то, чего вы не фильтровали, — вспомните про эти четыре имени.

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

openclaw mcp add files \
  --command npx \
  --arg -y \
  --arg @modelcontextprotocol/server-filesystem \
  --arg "$HOME/Documents" \
  --include 'read_file,list_directory,search_files'
openclaw mcp doctor files --probe

Шаг 5. Подтверждения вызовов

Если агент работает через рантайм Codex, у сохранённого сервера есть свой режим подтверждений, и он переопределяет режим, унаследованный от прав сессии:

openclaw mcp configure memory --approval approve

Три значения: approve — не спрашивать вообще, prompt — спрашивать каждый вызов, auto — решать по аннотациям безопасности, которые объявил сам инструмент. Флаг записывает в определение сервера поле codex.defaultToolsApprovalMode и действует только на проекцию в потоки Codex app-server; на другие рантаймы он не влияет.

Два предупреждения из документации, которые стоит принять всерьёз. Первое: approve ставьте только тем серверам, которым доверяете как собственному коду, — вы снимаете последний ручной барьер. Второе: mcp probe и mcp doctor --probe специально предупреждают, когда сервер стоит в режиме auto, но ни один его инструмент не объявил аннотаций безопасности. Это значит, что «автоматически» решать не по чему, и режим фактически вырождается.

Правка конфига напрямую

CLI удобен для типовых операций, но полная картина живёт в конфиге. Найти активный файл:

openclaw config file

По умолчанию это ~/.openclaw/openclaw.json; путь можно переопределить переменной OPENCLAW_CONFIG_PATH. Определения серверов лежат в блоке mcp.servers:

{
  mcp: {
    servers: {
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
        enabled: true,
        connectionTimeoutMs: 5000,
        requestTimeoutMs: 20000,
        toolFilter: {
          include: ["search", "read_*"],
        },
      },
    },
  },
}

Ключ enabled: false — недооценённая вещь: он оставляет определение в конфиге, но исключает сервер из обнаружения и проекции инструментов. Это правильный способ временно выключить сервер вместо того, чтобы удалять его и потом собирать заново по памяти.

И встречное предупреждение: прямая правка файла редактором разрешена, но запущенный шлюз считает такие изменения недоверенными, пока они не пройдут валидацию. Невалидная правка не подхватится горячей перезагрузкой, а на старте может уронить запуск. Если конфиг развалился — чинит openclaw doctor --fix.

Безопасность: три места, где протекает

Первое — секреты в конфиге. Держите учётные данные вне литералов. В заголовках и переменных окружения ссылайтесь на подстановку вида ${MCP_REMOTE_TOKEN}, а не на сам токен, а сами значения кладите в общее хранилище секретов: openclaw secrets store set <ИМЯ>. Это не теоретическая рекомендация — openclaw mcp doctor отдельно предупреждает, когда в headers или env лежит похожее на секрет литеральное значение, именно чтобы оператор успел его оттуда убрать. Чувствительные части url и заголовки в логах и в выводе status маскируются, но это про вывод, а не про файл на диске.

Второе — окружение локального сервера. Здесь OpenClaw защищает вас сам, и об этом полезно знать заранее, потому что поведение выглядит как баг. Перед запуском stdio-сервера из блока env вырезаются переменные, через которые можно подменить интерпретатор или подсунуть свой пролог: перехватчики старта вроде NODE_OPTIONS, PYTHONSTARTUP, PERL5OPT, RUBYOPT, BASHOPTS, KSH_ENV, а также префиксы DYLD_*, LD_* и BASH_FUNC_*. Они удаляются молча, с записью предупреждения в лог. Обычные учётные переменные при этом работают — есть явный список разрешённых, куда входят GITHUB_TOKEN, GH_TOKEN, GITLAB_TOKEN, NPM_TOKEN, NODE_AUTH_TOKEN, DATABASE_URL, MONGODB_URI, REDIS_URL, AMQP_URL, ключи AWS и Azure, прокси-переменные и произвольные *_API_KEY. А вот AWS_CONFIG_FILE и AWS_SHARED_CREDENTIALS_FILE остаются заблокированными, потому что указывают на файлы с учётными данными, а не несут значение сами. Если вашему серверу правда нужна заблокированная переменная — задайте её процессу шлюза, а не в env сервера.

Третье — сам факт, что инструмент вызывается кодом, а не человеком. Сервер прямого управления рабочим столом наследует права процесса, который его запустил; файловый сервер видит ровно то дерево, которое вы ему отдали. Никакая настройка OpenClaw не сузит это задним числом — сужать надо на входе, узким include и узкими аргументами запуска. Если ставки высоки и нужен взгляд со стороны, мы разберём, какие инструменты ваш агент на самом деле может вызвать, и что произойдёт, если он вызовет их не вовремя.

И ещё одно, чисто эксплуатационное: sslVerify: false существует, но это переключатель для явно доверенных приватных HTTPS-эндпоинтов, а не способ «побороть ошибку сертификата». Для приватных сервисов правильный путь — mTLS через clientCert и clientKey.

Таймауты, параллельность и время жизни соединений

Три поля, до которых доходят только после первых проблем, — а стоило бы сразу.

• connectionTimeoutMs — таймаут подключения к серверу, в миллисекундах.
• requestTimeoutMs — таймаут одного запроса MCP, в миллисекундах. Медленный сервер без этого поля способен съесть весь ход агента.
• supportsParallelToolCalls: true — подсказка, что к этому серверу можно обращаться параллельно. Это именно подсказка: адаптеры рантайма сами решают, воспользоваться ей или нет.

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

Про время жизни: рантаймы MCP, привязанные к сессии, живут между ходами — они не пересоздаются после каждого ответа. Отмирают они при сбросе или удалении сессии, при явной остановке, при значимом изменении конфига сервера и при остановке шлюза; дочерние stdio-процессы при этом завершаются. Если хочется выселять их по простою, есть mcp.sessionIdleTtlMs — необязательный таймаут в миллисекундах: не задан или 0 — выселения нет, положительное значение включает его (например, 3600000 — час).

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

Что ломается чаще всего

Сервер виден в настройках, но инструментов нет. Запустите openclaw mcp doctor <имя> --probe. Если соединение есть, а ожидаемых инструментов нет — смотрите toolFilter.include и toolFilter.exclude. Второй по частоте виновник — профиль инструментов агента: в обычных профилях coding и messaging настроенные MCP-инструменты видны, а профиль minimal их скрывает. И есть явный выключатель tools.deny: ["bundle-mcp"], который отключает их совсем; если он где-то прописан, вы будете чинить конфиг сервера бесконечно.

Stdio-сервер не стартует. Проверьте, что command разрешается в окружении процесса шлюза — не в вашем интерактивном шелле, а именно в том, под которым запущен шлюз. Это разные окружения, и npx, прекрасно работающий у вас в терминале, может отсутствовать у сервиса. Проверьте, что cwd существует. Аргументы должны лежать в args, а не быть приклеены к команде. Диагностику из stderr ищите в отладочном логе по префиксу bundle-mcp:<имя>:; вывод без перевода строки буферизуется до 250 мс, а строка длиннее 8 КиБ обрезается с пометкой [stderr line truncated].

Изменения не доезжают до работающего агента. Команда openclaw mcp reload сбрасывает кэшированные рантаймы только текущего процесса CLI. Шлюзу или агенту, работающему в другом процессе, нужна своя перезагрузка, публикация конфига или перезапуск. Это ровно то место, где рождается «я же перезагрузил» — перезагружен был не тот процесс.

Сервер есть в другом реестре. Команды list, show, set и unset читают и пишут только блок mcp.servers в конфиге OpenClaw. Серверы из отдельного реестра config/mcporter.json они не показывают — для него своя команда, mcporter list. Если сервер «точно подключён», но openclaw mcp list его не видит, посмотрите там.

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

1. Определились с транспортом: stdio для локального процесса, streamable-http или sse для удалённого.
2. openclaw mcp add <имя> … — сохранили определение.
3. openclaw mcp doctor <имя> --probe — доказали, что сервер отвечает и отдаёт инструменты.
4. openclaw mcp tools <имя> --include '…' — сузили набор инструментов до нужного.
5. Для HTTP с авторизацией: auth: "oauth" + openclaw mcp login <имя>, затем status --verbose для подтверждения.
6. Проставили connectionTimeoutMs и requestTimeoutMs, чтобы медленный сервер не съедал ход.
7. Убедились, что в headers и env нет литеральных секретов — doctor об этом предупредит.
8. Повторили doctor --probe после любой правки конфига руками.

Частые вопросы

Можно ли подключить MCP-сервер без командной строки?

Да. В Control UI это Settings → MCP → Add server: имя, транспорт, затем URL для HTTP-транспортов или команда с аргументами для stdio. Есть и путь из чата: + → Connectors → Add MCP server…, там же выбирается область действия — только текущая сессия или везде. Для тонких вещей — заголовков, переменных окружения, метаданных OAuth, TLS, таймаутов и фильтров — всё равно понадобится редактор конфига на той же странице. И проверку живого подключения интерфейс за вас не сделает: doctor --probe остаётся обязательным.

Что будет, если MCP-сервер недоступен в момент запроса?

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

Нужно ли перезапускать агента после добавления сервера?

При включённой горячей перезагрузке шлюза изменённые и удалённые серверы выводятся из работы сразу, и следующий ход обнаруживает уже новое определение. Неизменённые серверы сохраняют соединения и кэш инструментов, в том числе для уже идущих ходов. А вот openclaw mcp reload действует только на текущий процесс CLI — шлюзу в другом процессе нужен свой перезапуск.

Чем include отличается от отключения сервера?

toolFilter.include оставляет сервер подключённым и урезает список инструментов, попадающих в контекст. enabled: false оставляет определение в конфиге, но полностью исключает сервер из обнаружения. Первое — про аккуратность, второе — про паузу. Удаление определения командой unset — про «этот сервер нам больше не нужен»; она, кстати, завершается ошибкой, если сервера с таким именем нет.

Насколько всё это устойчиво от версии к версии?

Имена подкоманд add, set, configure, tools, probe, doctor, login, logout, list, show, status, reload, unset стабильны, и общая схема «сохранить → проверить → отфильтровать» не менялась. Меняется набор полей в определении сервера: за последние версии добавились per-requester OAuth, привязка к профилю авторизации, блок проекции в Codex. Поэтому дату и версию проверки мы и пишем в начале статьи — сверяйтесь с документацией на своей версии, а не с чужим постом двухлетней давности.

Когда не стоит делать это самому

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

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