Клиент
Claude Code. Он читает конфиг при старте сессии.
Гайд · Claude Code MCP
Пошаговый гайд: claude mcp add, .mcp.json, проверка списка tools и ошибки, из‑за которых сервер «есть в конфиге», но агент им не пользуется
Разобрать MCP в TelegramАгент в чате умеет рассуждать. Без MCP он не умеет сам открыть репозиторий, прочитать файл или положить черновик в WordPress. Вы копируете куски из браузера в промпт — и теряете время.
Официальный критерий простой: подключайте сервер, когда ловите себя на копипасте из другого инструмента в чат. Claude Code — продукт Anthropic. Из России вход и оплата часто идут через VPN и иностранную карту. Если CLI не открывается, тот же MCP-сервер можно повесить на другой клиент — но конфиг будет другим, не копируйте файлы слепо.
Главное
Клиент видит tools и вызывает их у сервера. Агент не «знает GitHub» сам по себе — он видит инструмент в списке.
claude mcp list.имя -- npx -y пакет. Удалённый: --transport http и URL.После правки .mcp.json сессию нужно перезапустить. Проектный сервер ещё и ждёт Approve. Секреты — в переменных и заголовках, не в git. WordPress — только черновик.
MCP (Model Context Protocol) — открытый протокол, по которому ИИ-клиент договаривается с отдельной программой: какие есть инструменты, как их вызвать, что вернуть. Метафора «USB-C для ИИ» здесь уместна один раз: один разъём, разные устройства.
Маркер: простыми словами. MCP — это не «ещё одна нейросеть». Это договорённость: клиент спрашивает «какие у тебя кнопки?», сервер отвечает списком tools, клиент нажимает кнопку, сервер ходит в GitHub, файлы или WordPress и возвращает результат.
MCP-сервер — программа, которая эти кнопки отдаёт. MCP-клиент — программа, которая их нажимает. В этой статье клиент — Claude Code (командная строка и сессия claude). Сервер — отдельный процесс или HTTP-адрес.
Цепочка всегда одна, меняются только ящики с настройками.
Claude Code. Он читает конфиг при старте сессии.
Запись «как запустить сервер»: команда, URL, переменные, заголовки. Лежит в ~/.claude.json или в .mcp.json в корне проекта.
Процесс на вашем компьютере или HTTP-точка. Он объявляет tools.
То, куда сервер ходит руками: диск, GitHub API, REST WordPress.
Агент не «знает GitHub». Он видит tool вроде «прочитать файл в репозитории» и вызывает его. Если tool в списке нет — агент гадает по памяти и выдумывает команды.
Маркер: простыми словами. MCP-сервер — это адаптер. С одной стороны протокол (tools), с другой — конкретный сервис. Без адаптера агент видит только чат.
Плагин к редактору меняет интерфейс: кнопки, подсветка, панель. MCP-сервер не рисует кнопки в IDE. Он даёт агенту вызовы: прочитать, создать, запросить.
Скилл или файл правил (как писать код, какой тон) — это инструкция в тексте. Инструкция не открывает API. MCP — руки. Правила — как этими руками пользоваться. Сегодня разбираем только руки: подключение, проверка, доступ. Как писать файлы правил для агента — отдельная тема, её здесь не разворачиваем.
Правила говорят, как работать. MCP даёт, чем работать. Пока в /mcp нет имён tools, агент будет рассуждать вместо вызова.
Успех — не строка в JSON и не сообщение Added …. Успех — три факта подряд:
claude mcp list показывает сервер со статусом Connected.
В сессии /mcp видны имена tools, не пустой список.
На промпт «покажи tools и вызови один безопасный» агент реально вызывает инструмент, а не пересказывает документацию.
claude mcp listПроцесс живой или HTTP отвечает.
Нужен вход (OAuth), конфиг уже есть.
Команда не стартовала, URL мёртвый, нет Node, нет -y.
Проектный сервер из .mcp.json ещё не одобрен.
claude mcp add пишет конфиг и печатает Added. Это сохранение настроек, не health-check.
Дальше отдельная проверка. Сервер может быть в файле и при этом:
"type": "http");Пока нет имён tools в /mcp, агент будет «знать, что GitHub существует», и выдумывать curl. Это и есть гадание.
Hero показал, как прописать MCP. Сцена ниже — почему зелёный конфиг не равен рукам агента: сначала list, потом права, потом ловушка HTTP 307.
/mcp./mcp → /mcp/ рвёт тело POST: initialize жив, вызов умер.claude, не перезапуск диалога.Дальше — add и файл .mcp.json за один проход; таблицу развилки разберём в секции проверки.
Цикл ~48 с · конфиг → list → права → 307 → tools
Ниже — маршрут, который новичок повторяет за вечер. Сначала один учебный HTTP-сервер без секретов, потом локальный пакет.
Убедитесь, что команда claude запускается (Claude Code CLI установлен и вы залогинены).
Добавьте сервер из официального quickstart — документацию самого Claude Code. Все флаги (--transport, --env, --scope, --header) ставьте до имени сервера. Иначе CLI ругается unknown option.
Нужно увидеть claude-code-docs и ✓ Connected. Если Failed to connect — подождите (первый заход качает пакеты) и повторите. При долгом старте: MCP_TIMEOUT=60000 claude.
Запустите сессию claude, введите /mcp. Должны появиться tools этого сервера.
Подключите локальный пример — Playwright, если тестируете браузер, или любой пакет с -y. Двойной прочерк -- обязателен: всё после него уходит серверу. Без -- Claude Code пытается разобрать чужие флаги как свои.
claude mcp list — Connected. /mcp — список tools с именами. Промпт «вызови один tool и покажи сырой ответ» даёт вызов, а не текст «я бы мог…».
Пакетный менеджер ждёт подтверждение в интерактиве, сервер «висит», в list — Failed. Решение: всегда -y.
--transport http после имени ломает разбор. Решение: сначала все -t/-s/-e/-H, потом имя, потом URL или -- команда.
Так пишут некоторые англоязычные воркшопы. В актуальном Claude Code этих флагов нет, будет unknown option --command. Решение: локальный сервер — только схема имя -- команда аргументы.
Флаг жадный: имя читается как KEY=value. Между --env и именем нужен ещё один флаг либо другой порядок, как в официальном quickstart Claude Code.
Снять сервер: claude mcp remove <имя>. Посмотреть карточку: claude mcp get <имя>.
claude mcp add безопаснее для новичка: CLI сам кладёт запись в нужный ящик и меньше шансов опечататься в поле type.
Ручной .mcp.json нужен, когда команда должна жить в git и её видит вся команда. Для HTTP поле "type": "http" обязательно (допустим алиас streamable-http). Если указать только url без type, Claude Code решит, что это stdio, и пропустит сервер с ошибкой has a "url" but no "type".
После ручной правки JSON выйдите из сессии и запустите claude заново. Файл читается при старте, не на лету.
Подстановка секретов в JSON: ${VAR} и ${VAR:-default} в command, args, env, url, headers. Если переменной нет, конфиг всё равно грузится, в list будет предупреждение, в значение уйдёт нераскрытый ${VAR} — tools при этом часто пустые.
Пробелы в начале и конце значений не обрезаются. Токен, скопированный с переносом строки, ломает заголовок. Это частый артефакт копипаста.
Маркер: простыми словами. Scope — это «в какой ящик положили сервер». Положили не туда — в текущей папке агент его не видит, хотя «вчера же добавляли».
| Scope | Где лежит | Кто видит | В git |
|---|---|---|---|
local (по умолчанию) | ~/.claude.json, внутри этого проекта | только вы, только эта папка | нет |
user | ~/.claude.json, общий список mcpServers | вы, во всех проектах | нет |
project | .mcp.json в корне репозитория | все, кто клонировал | да |
Команда: --scope local / user / project (коротко -s). Сменить ящик нельзя «переездом»: claude mcp remove <имя> --scope local, затем add с новым scope.
local для MCP — это не файл .claude/settings.local.json. MCP local живёт в ~/.claude.json. Пути вроде ~/.claude/.mcp.json или %APPDATA%\Claude\mcp.json Claude Code не читает.
Если одно имя встречается в нескольких ящиках, побеждает одна запись целиком, поля не сливаются. Практическое правило: не плодите тёзок. Проектные серверы при первом запуске — Pending approval. Сброс выборов: claude mcp reset-project-choices.
Добавили сервер из каталога A с scope local, открыли проект B — сервера нет. Лечится --scope user или повторный add из нужного корня.
Маркер: простыми словами. Транспорт — способ доставки вызова. Stdio: Claude Code сам запускает программу на вашем компьютере и говорит с ней через стандартный ввод-вывод. HTTP: программа уже крутится где-то в сети, клиент ходит на URL.
SSE (--transport sse) помечен как устаревший. Где есть обычный HTTP — берите HTTP.
Stdio — дефолт. Типичная команда: claude mcp add <имя> -- npx -y <пакет>.
Где рвётся:
-- — флаги пакета съедает сам Claude Code.-y — npx ждёт ввод..bashrc. Если Node ставили через nvm, симптом: env: 'node': No such file or directory. В env сервера нужен PATH с полным путём к node/npx.workspace, claude-in-chrome, computer-use, Claude Preview, Claude Browser. Назовите сервер иначе.Для WordPress через WP-CLI по SSH stdio часто проходит мелкий handshake (claude mcp list зелёный), а большой ответ зависает из‑за буфера 4 КБ без TTY. Практичный выход — HTTP-прокси, не «ещё один SSH».
Команда: claude mcp add --transport http <имя> https://хост/путь.
Слэш в конце. Многие HTTP-серверы отвечают 307 с /mcp на /mcp/. Клиенты MCP часто не идут за редиректом или теряют тело POST. Симптом: initialize проходит, вызов tool — 404 или «session terminated». В URL ставьте тот путь, который сервер реально монтирует, не надейтесь на редирект.
Nginx. Для длинных ответов нужны proxy_buffering off, proxy_cache off, HTTP/1.1 и большой proxy_read_timeout. Иначе клиент думает, что сокет жив, а стрим придёт только когда соединение закроют.
Голый домен WordPress. Для Adapter канон — полный путь вида https://сайт/wp-json/mcp/mcp-adapter-default-server. Голый домен включает старый режим и бьёт в устаревший endpoint → 404.
Диагностика — не «потыкать чат». Сначала list, потом карточка, потом сессия.
claude mcp list — статус Connected, не Pending и не Failed.
claude mcp get <имя> — команда, URL, env без живого секрета в скриншоте.
Сессия claude → /mcp — имена tools.
Только потом задача на вызов инструмента.
После любой ручной правки .mcp.json — полный выход и новый claude. Claude Desktop после правки своего файла тоже требует рестарт приложения, не «ещё один чат».
| Что видите | Что проверить первым |
|---|---|
Нет в list вообще | Другой scope; add из другой папки; опечатка имени |
Failed to connect | -y, --, PATH/nvm, таймаут, живой URL |
Pending approval | Approve в /mcp или reset-project-choices |
Needs authentication | В сессии /mcp → Authenticate или claude mcp login <имя> |
| Connected, tools пустые | Нет env/ключа; нераскрытый ${VAR}; HTTP без type |
| Connected, tools есть, агент не вызывает | Промпт без задачи на tool; слишком много мёртвых серверов; сервер не про тот контур |
Не ищите одну «магическую» ошибку. Это развилка по таблице, не одна кнопка.
Не коллекционируйте каталог «десять лучших». Возьмите то, куда вы и так копипастите.
Учебный контур без секретов: HTTP-документация Claude Code (шаг 2 выше). Рабочий контур: файлы и GitHub. WordPress — отдельная секция, только черновики. Тот же протокол подходит и к мессенджерам — сегодня их не разбираем, чтобы не смешать с другими пайплайнами.
Filesystem MCP даёт агенту чтение (и при желании запись) локальных файлов. Имеет смысл, если агент должен сам открыть бриф, таблицу, markdown — а не ждать вставку в чат. Права — минимальные: каталог проекта, не весь домашний диск.
В актуальном контуре чаще подключают по HTTP, а не старым stdio-пакетом с токеном в env. Схема: URL https://api.githubcopilot.com/mcp/ и заголовок Authorization: Bearer … через --header (коротко -H). PAT — с узкими scope, лучше read-only. В git заголовок не кладут живым: ${GITHUB_TOKEN} или scope local/user.
Не коммитьте .mcp.json с настоящим PAT. Командный файл — только подстановка переменной.
Playwright MCP — если агент должен сам пройти сценарий в браузере. Figma MCP — если в работе есть макеты. Blender MCP — если 3D-сцена реально в процессе. Подключайте сервер, когда копипаст уже случился дважды. Не когда прочитали список пакетов.
WordPress MCP Adapter превращает abilities сайта в MCP tools. Пакет — официальный: github.com/WordPress/mcp-adapter. Это не отдельный «бренд для H1»: спрос узкий, но для контент-завода рука как раз сюда.
Фундамент — Abilities API в WordPress 6.9. Дефолтный сервер: mcp-adapter-default-server. Базовые tools адаптера: обнаружить abilities, прочитать карточку, выполнить. Ядровые abilities сайта в MCP не светятся, пока у них не стоит meta.mcp.public = true.
wp mcp-adapter serve --server=mcp-adapter-default-server --user=…
Прокси npx -y @automattic/mcp-wordpress-remote@latest и переменные WP_API_URL, WP_API_USERNAME, WP_API_PASSWORD.
Self-hosted вход — Application Password. У WordPress.com — OAuth. Готовый OAuth «из коробки» на обычном хостинге не обещайте.
Официальные туториалы и воркшопы сходятся: агент создаёт пост со статусом draft, не publish. Человек публикует. Для контент-завода это правильный дефолт.
Маркер: простыми словами. Ability в WordPress — именованное действие сайта («создать черновик», «получить инфо о сайте») с проверкой прав. Адаптер показывает это действие агенту как tool. Нет public в мета — агент действие не увидит.
JSON для прокси в других клиентах часто верный. Команду Claude Code берите только из официальной доки: npx после --, без выдуманных --command/--args.
Маркер: простыми словами. Application Password — пароль приложения в профиле пользователя WordPress, отдельно от пароля входа в админку. Его дают MCP-прокси. Если слить его, злоумышленник действует от имени этого пользователя.
Правила, которые совпадают с позицией команды WordPress:
permission_callback, не «всегда true»;draft.Журнал. У Adapter есть запись ошибок в PHP error log. Готового экрана в админке «кто что опубликовал» из коробки нет. Полный audit — свой хук или сторонний плагин. Не ждите, что Adapter станет журналом публикаций сам.
WP_API_URL — полный REST-путь, не голый домен. После смены пароля — новый add и рестарт сессии.
Когда MCP уже кладёт черновик в WordPress, следующий шаг — собрать конвейер вокруг этого: Make, автопубликация, вайбкодинг. Практический разбор — на странице обучения по автоматизации и вайбкодингу.
Cursor — соседний MCP-клиент, не «тот же Claude Code с другим окном». У него свой файл (часто .cursor/mcp.json) и свой экран Settings → Tools & MCP.
VS Code — третий вариант: объект servers, не mcpServers, файл .vscode/mcp.json.
Схема «скопировал JSON из Claude Code в Cursor» иногда сработает для stdio-пакета с npx -y, но пути, имена полей и OAuth — разные. Не переносите ~/.claude.json целиком.
Если Claude Code из России не открывается, Cursor может быть рабочим путём к тем же серверам — при условии, что вы заново прописываете клиентский файл, а не «переименовываете» ящик Claude.
Если собираете стек вокруг AI-IDE и MCP в редакторе, попробовать Cursor с бонусом по реферальной программе можно по этой ссылке. Конфиг всё равно пишите заново — это другой клиент, не «тот же Claude Code».
Маркер: простыми словами. OAuth здесь — вход в сервер через браузерное «разрешить доступ», без вставки вечного токена в JSON. В Claude Code это выглядит как статус Needs authentication, затем /mcp → Authenticate или claude mcp login <имя>.
Токены в JSON не кладут. Ни PAT, ни Application Password, ни session-строки. Несколько агентов на одной машине с широкими правами — это те же руки без изоляции: конфликт задач быстро портит чужие файлы.
.mcp.json, который уходит в git;claude mcp get для коллеги;${GITHUB_TOKEN} / ${WP_API_PASSWORD} в командном .mcp.json;--header и --env в scope local или user;Старый совет «не ставьте десять серверов — контекст умрёт» частично устарел. По умолчанию включён MCP Tool Search: полные схемы tools подтягиваются по необходимости, жёсткого потолка на число инструментов нет. Вернуть старое «грузить всё» можно флагом ENABLE_TOOL_SEARCH=false. Если сервер нужен на каждом ходу — alwaysLoad: true в записи (актуальные сборки CLI).
Маркер: простыми словами. Tool Search — отложенная загрузка описаний кнопок. Имена и инструкции сервера всё равно занимают место. Мёртвый сервер, которым никто не пользуется, всё равно шумит в сессии.
Актуальное правило: не копить зомби. Для облачных SaaS — HTTP и OAuth, не зоопарк локальных npx. Для GitHub и WordPress — read-only пользователь, пока не доказали, что агенту нужна запись.
Спрос «как создать MCP-сервер» слабый, и это честно. Сначала добейтесь Connected и живого вызова на чужом пакете. Свой сервер на Python — следующий уровень, когда ни один готовый адаптер не закрывает ваш сервис.
Пока нет list → /mcp → вызов, писать SDK рано: вы будете отлаживать сразу и протокол, и бизнес-логику.
~/.claude.json + проектный .mcp.json. Импорт с Desktop в CLI на macOS/WSL: claude mcp add-from-claude-desktop. Настольное приложение Claude Code добавляет серверы через Connectors, не через файл чат-Desktop.
Чат-приложение, не то же самое, что Claude Code: claude_desktop_config.json — свои пути на macOS, Windows и Linux.
Тезис «в веб-Claude MCP нет» устарел: коннекторы учётной записи подтягиваются в CLI при том же логине, веб-сессия умеет читать .mcp.json репозитория. Не копируйте старые гайды на эту тему.
Программа-адаптер: отдаёт агенту список tools и выполняет вызов к сервису (файлы, GitHub, WordPress). Это не чат и не «ещё одна модель».
claude mcp add --transport http <имя> <url> для HTTP или claude mcp add <имя> -- npx -y <пакет> для локального процесса. Флаги — до имени. Потом claude mcp list и /mcp.
Add пишет конфиг за вас (часто в ~/.claude.json). .mcp.json — командный файл в корне репозитория, scope project, его видят все, кто клонировал. После ручной правки — рестарт сессии.
Конфиг ≠ здоровье. Проверьте list, scope, Approve, -y и --, поле type у HTTP, env-ключи, рестарт. Connected с пустым списком tools — почти всегда нет секрета или переменная не раскрылась.
Локальный пакет на вашей машине — stdio (-- и npx). Сервис в сети или WordPress на хостинге — HTTP. SSE не берите, если есть HTTP.
claude mcp list, затем claude mcp get <имя>, затем /mcp в сессии. Рабочий промпт — после имён tools.
Да. GitHub — HTTP плюс заголовок с PAT. Filesystem — каталог проекта, не весь диск. Playwright — только если агенту реально нужен браузер.
Если агент должен класть черновики в WP — да. Отдельный пользователь, пост только как draft, полный URL Adapter, не голый домен.
Заново в файле Cursor, не копируя ~/.claude.json. Поля и OAuth другие. VS Code — ещё один формат.
В git — нет. В командном файле — только ${VAR}. Живые секреты — scope local/user, OAuth через /mcp, Application Password на отдельном WP-пользователе.
Нет. Status line оформляет сессию и к tools не относится.
Определение. MCP — протокол, по которому клиент получает от сервера список инструментов и вызывает их. Подключение — запись в конфиг плюс живой процесс или URL. Проверка — claude mcp list и имена tools в /mcp. Пока нет вызова tool, агент гадает.
Итог. Сначала один сервер без секретов, потом GitHub или файлы, потом WordPress-черновик. На каждом шаге — list, а не вера в строку Added. Секреты — в переменных. Публикацию на проде человек не отдаёт агенту по умолчанию.
Что проверяли по источникам. Команды, scopes и статусы — официальный quickstart Claude Code. Adapter, прокси и пост как draft — материалы WordPress и репозиторий адаптера. Синтаксис --command/--args в сторонних воркшопах в CLI не работает. 307 на /mcp/, буфер nginx и nvm без PATH — частые причины «Connected, а вызова нет».