🔌 MCP серверы
MCP (Model Context Protocol) — протокол подключения внешних инструментов к Claude Code. Три точки входа в глобальном конфиге + project-scope серверы через .mcp.json.
⚙️ Настройка
→
🗂️ Иерархия
→
🔌 MCP
→
🪝 Hooks
На предыдущих шагах вы настроили глобальный
~/.claude/settings.json и иерархию CLAUDE.md.
Теперь разберёмся с MCP: что это, как работает экономия токенов, и какие серверы нужны для каких задач.
🏗️ Архитектура: три точки входа
На этом сервере MCP организован в три уровня. Глобальные серверы — в ~/.claude.json, проектные — в .mcp.json каждого проекта.
Claude Code CLI
│
├── Tool Search (автоматически, ~5 700 токенов при старте)
│ └── подгружает схемы инструментов по запросу — не грузит всё сразу
│
├── ~/.claude.json — глобальные (3 entry-point):
│ ├── ruflo · HTTP → localhost:3100 · агенты, swarm, vector memory
│ ├── MCP_DOCKER · docker mcp gateway run · 7 серверов в контейнерах:
│ │ ├── context7 · fetch · memory · node-sandbox
│ │ ├── playwright · sequentialthinking · youtube_transcript
│ └── powershell · npx mcp-powershell-exec · Windows-команды
│
└── .mcp.json — project-scope (только для этого проекта):
├── laravel-boost · cmd /c docker exec <app> php artisan boost:mcp
├── postgres · npx @modelcontextprotocol/server-postgres <url>
└── mysql / tavily / gsc / ... — по необходимости
│
├── Tool Search (автоматически, ~5 700 токенов при старте)
│ └── подгружает схемы инструментов по запросу — не грузит всё сразу
│
├── ~/.claude.json — глобальные (3 entry-point):
│ ├── ruflo · HTTP → localhost:3100 · агенты, swarm, vector memory
│ ├── MCP_DOCKER · docker mcp gateway run · 7 серверов в контейнерах:
│ │ ├── context7 · fetch · memory · node-sandbox
│ │ ├── playwright · sequentialthinking · youtube_transcript
│ └── powershell · npx mcp-powershell-exec · Windows-команды
│
└── .mcp.json — project-scope (только для этого проекта):
├── laravel-boost · cmd /c docker exec <app> php artisan boost:mcp
├── postgres · npx @modelcontextprotocol/server-postgres <url>
└── mysql / tavily / gsc / ... — по необходимости
⚡ Tool Search — экономия токенов
💡
Tool Search — встроенный механизм CC, не отдельный сервер.
Включается автоматически при 5+ серверах. Загружает ~5 700 токенов при старте вместо 82 000.
Переменная
MCP_TOOL_SEARCH=1 устарела с CC 1.0+ (январь 2026) — убрана из конфига.
До: ~82 000 токенов при старте
После: ~5 700 токенов ✓
+76 000 токенов свободно
Когда нужен конкретный инструмент — CC запрашивает его схему у нужного сервера и подгружает. Playwright (23 инструмента) грузится только когда вы просите «открой браузер», context7 — когда «найди документацию по Laravel».
🌐 Глобальные MCP серверы
Прописаны в ~/.claude.json. Доступны во всех проектах автоматически.
ruflo
http://localhost:3100/mcp
глобальный · HTTP
Агентная платформа: swarm-оркестрация, vector memory, task management, hooks. Docker-контейнер на порту 3100. Авторизация через Bearer токен.
MCP_DOCKER Gateway
docker mcp gateway run
глобальный · Docker Gateway
Один entry-point → 7 серверов в изолированных контейнерах. Конфигурируется через Docker Desktop GUI. Каждый сервер запускается по требованию.
powershell
npx mcp-powershell-exec
глобальный · stdio
Windows PowerShell команды через MCP. Процессы, диски, сервисы, мониторинг. Нужен отдельно от Docker Gateway — должен видеть Windows-хост напрямую.
Что внутри Docker Gateway
| Сервер | Инструментов | Назначение |
|---|---|---|
context7 | 2 | Актуальная документация: Laravel, Vue, Nuxt, FastAPI, React... |
fetch | 1 | HTTP-запросы из изолированного контейнера |
memory | 9 | KV-хранилище между сессиями (entities + relations) |
node-code-sandbox | 7 | Безопасное выполнение JS без выхода в сеть |
playwright | 23 | Браузерная автоматизация, E2E тесты, скриншоты |
sequentialthinking | 1 | Пошаговый структурированный анализ задач |
youtube_transcript | 4 | Транскрипты YouTube видео |
📁 Project-scope MCP серверы
Прописываются в .mcp.json в корне проекта. Активны только в этом проекте.
laravel-boost
cmd /c docker exec <app> php artisan boost:mcp
per-project · Laravel
MCP внутри Laravel-контейнера. Роуты, Eloquent модели, события, конфиг, Artisan команды — всё через MCP без чтения PHP-файлов. Каждый проект — своё имя контейнера.
postgres
npx @modelcontextprotocol/server-postgres <url>
per-project · БД
Запросы к PostgreSQL, интроспекция схемы. Запускается через npx (не Docker) — только так видит Windows localhost и порт пробрасываемый в хост.
mysql
npx @benborla29/mcp-server-mysql
per-project · БД
MySQL / MariaDB запросы и интроспекция схемы. Для Laravel/Bitrix проектов. Credentials через env-переменные в .mcp.json (не коммитить!).
google-search-console
npx mcp-gsc
per-project · SEO
Google Search Console API: позиции, CTR, запросы, индексация. Требует service-account.json. Только для SEO-проектов.
tavily
npx tavily-mcp
per-project · поиск
Веб-поиск и исследование в реальном времени через Tavily API. Для контент-проектов и исследовательских задач.
claude-in-chrome
mcp__claude-in-chrome__*
per-project · UI
Управление живым браузером Chrome из Claude. Клики, формы, скриншоты, GIF-запись сессий, чтение консоли. Расширение для Chrome.
📊 Матрица: что где прописывать
| MCP сервер | Laravel | Nuxt/Vue | Python | Где прописан |
|---|---|---|---|---|
ruflo |
✅ | ✅ | ✅ | ~/.claude.json (глобально) |
MCP_DOCKER (context7, playwright...) |
✅ | ✅ | ✅ | ~/.claude.json (глобально) |
powershell |
✅ | ✅ | ✅ | ~/.claude.json (глобально) |
laravel-boost |
✅ | ❌ | ❌ | .mcp.json (только Laravel) |
postgres |
✅ | ❌ | ✅ | .mcp.json (проекты с PG) |
mysql |
✅ | ❌ | ❌ | .mcp.json (Laravel/Bitrix) |
claude-in-chrome |
✅ | ✅ | ❌ | .mcp.json (UI-проекты) |
google-search-console |
❌ | ❌ | ✅ | .mcp.json (SEO) |
⚙️ Шаблоны .mcp.json
Laravel + laravel-boost + PostgreSQL (как notal)
// E:\Clients\laravel\myproject\.mcp.json
{
"mcpServers": {
"laravel-boost": {
"command": "cmd",
"args": ["/c", "docker", "exec", "-i", "myproject-app", "php", "artisan", "boost:mcp"]
},
"postgres": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-postgres",
"postgresql://user:pass@localhost:5432/mydb"]
}
}
}
⚠️
Windows: всегда
cmd /c docker, не просто docker!
На Windows "command": "docker" не работает напрямую из MCP — нужен cmd /c как оболочка.
Иначе laravel-boost не запустится.
Laravel + MySQL (Bitrix)
{
"mcpServers": {
"mysql": {
"command": "npx",
"args": ["-y", "@benborla29/mcp-server-mysql"],
"env": {
"MYSQL_HOST": "127.0.0.1",
"MYSQL_PORT": "3306",
"MYSQL_USER": "homestead",
"MYSQL_PASS": "secret",
"MYSQL_DB": "myproject"
}
}
}
}
SEO проект
{
"mcpServers": {
"google-search-console": {
"command": "npx",
"args": ["-y", "mcp-gsc"],
"env": { "GOOGLE_APPLICATION_CREDENTIALS": "E:/Clients/seo/service-account.json" }
},
"tavily": {
"command": "npx",
"args": ["-y", "tavily-mcp"],
"env": { "TAVILY_API_KEY": "tvly-ваш_ключ" }
}
}
}
🐳 Docker: только через MCP
⚠️
Bash(docker*) заблокирован в deny-списке.
Все docker-операции — через
mcp__docker__* инструменты.
На Windows Bash не видит docker без PATH-хака, MCP — всегда надёжнее.
| Задача | ❌ Bash (заблокирован) | ✅ MCP инструмент |
|---|---|---|
| Выполнить команду в контейнере | docker exec app php artisan... |
mcp__docker__docker_exec |
| Логи контейнера | docker logs app |
mcp__docker__docker_container_logs |
| Список контейнеров | docker ps |
mcp__docker__docker_list_containers |
| Перезапуск контейнера | docker restart app |
mcp__docker__docker_restart_container |
| Compose управление | docker compose restart |
mcp__docker__docker_compose_restart |
💡
Исключение: laravel-boost установка.
Установить пакет
laravel/boost можно только через PowerShell/cmd (не Bash):
docker exec -u root <container> composer require --dev laravel/boost
Это разовая операция, после неё — всё управление через mcp__laravel-boost__*.
📐 Где что хранится
// Порядок загрузки (низший → высший приоритет):
1. ~/.claude/settings.json // permissions, hooks, model — НЕ содержит MCP
2. ~/.claude.json // глобальные MCP: ruflo, MCP_DOCKER, powershell
3. ./.claude/settings.local.json // project-scope permissions (не коммитить)
4. ./.mcp.json // project-scope MCP: БД, laravel-boost (высший приоритет)
⚠️
Не коммитить .mcp.json с секретами! Добавить в
.gitignore. Пароли БД, API ключи — только в .mcp.json, не в глобальный конфиг.🔧 Отладка MCP
| Проблема | Причина | Решение |
|---|---|---|
| MCP сервер не видно в /mcp | Конфиг в неправильном файле | Глобальные → ~/.claude.json; проектные → .mcp.json |
| laravel-boost не запускается | Контейнер не запущен или неверное имя | Проверить mcp__docker__docker_list_containers, исправить имя в .mcp.json |
| laravel-boost: ошибка запуска на Windows | "command": "docker" без cmd оболочки |
Заменить на "command": "cmd", "args": ["/c", "docker", ...] |
| postgres MCP не видит БД | Неверный хост/порт в URL | Порт пробрасывается на хост — использовать localhost:5435, не docker-internal |
| Docker Gateway (MCP_DOCKER) не стартует | Docker Desktop не запущен | Запустить Docker Desktop, дождаться статуса Running |
| MCP_DOCKER: сервер падает с EOF | Сервер требует конфига через GUI (напр. filesystem) | Настроить через Docker Desktop → MCP Toolkit → CONFIG или убрать из registry.yaml |
| claude-in-chrome завис после алерта | JavaScript alert заблокировал события браузера | Закрыть диалог вручную в браузере, пересоздать вкладку |
| ruflo: ошибка авторизации | Bearer токен не совпадает | Токен в ~/.claude.json должен совпадать с RUFLO_TOKEN в docker-compose.yml |
✅ Итог
Глобальные MCP прописаны раз и работают во всех проектах. Для каждого Laravel-проекта — свой .mcp.json с именем контейнера и URL базы. Следующий шаг — Hooks для автоматизации.