Документация

Три шага до первого вызова

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

Быстрый старт Вызов инструмента Транспорты Middleware Коды ответов Проблемы

Быстрый старт

Токен выдаёт artisan-команда, эндпоинт — обычный JSON-RPC по HTTPS. Значение токена показывается один раз.

Выдать токен

Команда создаёт служебного пользователя и Personal Access Token с abilities mcp:read и mcp:write.

php artisan mcp:token \
  --name=dsh-prod

Только чтение: --abilities=mcp:read. Ротация: --revoke-all.

Подключить HTTP-клиент

Укажите URL эндпоинта и заголовок с токеном в конфигурации MCP-клиента.

mcpServers

{
  "mcpServers": {
    "dealshub": {
      "type": "http",
      "url": "https://mcp.dealshub.ru/mcp/dealshub",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Или запустить локально

STDIO-режим поднимает сервер в процессе рядом с проектом — без токена и сети. Доступ ограничен самим фактом запуска.

php artisan mcp:start dealshub

Клиент не умеет передавать заголовки

Токен можно передать query-параметром — middleware перенесёт его в Authorization и удалит из запроса, чтобы значение не попало в логи.

curl -X POST "https://mcp.dealshub.ru/mcp/dealshub?token=$MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Заголовки и вызов инструмента

Обязательный минимум — токен и Accept с поддержкой text/event-stream. Список инструментов со схемами возвращает метод tools/list.

Проверка соединения

tools/list

curl -X POST https://mcp.dealshub.ru/mcp/dealshub \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Вызов инструмента

tools/call

curl -X POST https://mcp.dealshub.ru/mcp/dealshub \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_products",
      "arguments": { "factory": "Zadoor", "width_mm": 800 }
    }
  }'

Заголовки запроса

Заголовок	Значение	Обязателен
`Authorization`	`Bearer <token>` — либо `?token=` в query	да
`Content-Type`	`application/json`	да
`Accept`	`application/json, text/event-stream`	да

HTTP или STDIO

Одна и та же кодовая база инструментов, разные способы доставки запроса.

HTTP — для удалённых агентов

Эндпоинт POST /mcp/dealshub.
Авторизация токеном Sanctum и abilities mcp:read / mcp:write.
Лимит 60 запросов в минуту на токен и журнал вызовов.

STDIO — для локального запуска

Команда php artisan mcp:start dealshub.
Без сети и токена — сервер общается с клиентом через стандартные потоки.
Доступ ограничен правами процесса: запускать только в доверенном окружении.

Что происходит с запросом

Слои выполняются по порядку; журнал вызовов пишется до проверки токена, поэтому отказы тоже видны.

1
ReorderJsonAccept
Приводит Accept к виду, ожидаемому MCP-транспортом.
2
AddWwwAuthenticateHeader
Добавляет заголовок WWW-Authenticate к ответу 401.
3
McpTokenFromQuery
Переносит ?token= в Authorization и удаляет параметр из запроса.
4
LogMcpCall
Пишет журнал вызовов, включая 401 и 429.
5
auth:sanctum
Проверяет Personal Access Token.
6
throttle:mcp
Лимит 60 запросов в минуту на токен.

Коды ответов

Ошибки валидации приходят внутри JSON-RPC-ответа с кодом 200 и result.isError: true — транспортный статус остаётся успешным.

200 Ответ JSON-RPC, в том числе result.isError при ошибке валидации
401 Токен отсутствует или недействителен
405 GET или DELETE на эндпоинт (разрешён только POST)
429 Превышен лимит запросов на токен

Ответы без ошибок

Инструменты чтения различают «нет данных» и сбой значением found, а не исключением.

Товар не найден

{ "found": false, "product_id": 4242 }

Заказ не найден

{ "found": false, "order_id": 4242 }

Недостаточно прав

{ "isError": true, "content": [{ "type": "text", "text": "Токену не разрешено действие «mcp:write»." }] }

Типовые проблемы

401 Unauthorized

Токен не передан, отозван или относится к другому окружению. Проверьте заголовок Authorization и что используется значение, показанное при выдаче.

405 Method Not Allowed

На эндпоинт пришёл GET или DELETE. MCP принимает только POST — проверьте настройку транспорта в клиенте.

429 Too Many Requests

Превышен лимит 60 запросов в минуту на токен. Разнесите вызовы по времени или заведите отдельный токен под другого агента.

Пустой result

Инструмент вернул found: false или пустую выдачу — это корректный ответ. Уточните фильтры: для каталога снимите only_active и in_stock_only.

Инструмент не виден

Клиент показывает список из tools/list. Убедитесь, что запрос уходит на /mcp/dealshub и заголовок Accept включает text/event-stream.

Запись отклонена

Для create_order, create_order_claim и save_seo_meta нужен токен с ability mcp:write. Проверьте abilities при выдаче токена.

Документы в репозитории

docs/mcp-api.md — полное описание API, инструментов и логирования.
docs/examples.md — примеры запросов и ответов.
docs/verification.md — сценарии проверки сервера.

Дальше: выберите инструмент в справочнике или посмотрите правила наценок.

Открыть инструменты