Сервер даёт агенту 88 инструментов для работы с Pyrus: формы, задачи, реестры, справочники, доступы, сотрудники, боты, телефония. Подключение занимает пять минут и состоит из двух независимых частей — и путаница между ними стоит дороже всего остального.
Это главное, что стоит понять до настройки. Здесь два уровня доступа, и они не заменяют друг друга.
Отвечает на вопрос «пустить ли вас на сервер вообще». Выдаётся отдельно на каждого
человека, передаётся в заголовке Authorization.
Ваш токен выдан отдельным сообщением.
Отвечают на вопрос «что вы увидите внутри Pyrus». Своего аккаунта у сервера нет — он работает от вашего имени и видит ровно то, что видите вы.
Это ваш логин и ключ безопасности из Pyrus.
Настроить только токен сервера и забыть реквизиты Pyrus. Тогда подключение
установится, список инструментов придёт — а любой вызов будет
падать, включая самые лёгкие. Со стороны это выглядит как перегрузка на больших
данных, и на этой ложной догадке легко потерять час. Сервер теперь отвечает на такое
прямо: no_credentials.
Откройте Pyrus в браузере под своей учётной записью.
Профиль → Настройки → Авторизация → Секретный API ключ.
Создайте ключ безопасности и скопируйте его. Ключ показывается один раз.
Ключ действует от вашего имени и со всеми вашими правами — храните его как пароль.
Адрес сервера:
https://mcp.pplus.software/mcp
Прежний адрес pyrus-mcp-production.up.railway.app продолжает
работать — это тот же сервер. Новые подключения настраивайте на
mcp.pplus.software, старые можно перевести без спешки.
Добавьте в конфигурацию MCP-серверов:
{
"mcpServers": {
"pyrus": {
"type": "http",
"url": "https://mcp.pplus.software/mcp",
"headers": {
"Authorization": "Bearer <ВАШ_ТОКЕН_MCP>",
"X-Pyrus-Login": "вы@ваша-почта.ru",
"X-Pyrus-Security-Key": "<ВАШ_КЛЮЧ_PYRUS>"
}
}
}
}Транспорт — streamable HTTP. Заголовки те же:
Authorization: Bearer <ВАШ_ТОКЕН_MCP>
X-Pyrus-Login: вы@ваша-почта.ru
X-Pyrus-Security-Key: <ВАШ_КЛЮЧ_PYRUS>
Content-Type: application/json
Accept: application/json, text/event-stream
Вместо пары «логин + ключ» можно передать готовый
X-Pyrus-Access-Token. Одного X-Pyrus-Login без ключа
недостаточно — это не пара, и работать не будет.
Быстрая проверка из терминала — подставьте свой токен:
curl -s -X POST https://mcp.pplus.software/mcp \
-H "Authorization: Bearer <ВАШ_ТОКЕН_MCP>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"2025-06-18","capabilities":{},
"clientInfo":{"name":"check","version":"1"}}}'200 — токен принят. 401 — токен неверный. Это проверяет только первый уровень; реквизиты Pyrus проверятся на первом же вызове инструмента.
Дальше в агенте попросите вызвать get_profile с summary: true — придёт ваше имя и организация.
| Задача | Инструмент |
|---|---|
| Кто я и в каком контуре | get_profile(summary: true) |
| Какие есть формы | get_forms |
| Что за поля у формы | get_form(form_id, summary: true) |
| Какие есть справочники | list_catalogs |
| Задачи по форме | get_registry(form_id, include_archived: true) |
include_archived: true обязателен. Без него приходят только открытые
задачи, и Pyrus об этом не сообщает — счёт молча занижается. На
одной проверенной форме это 681 задача вместо 3046.
Ответ инструмента целиком уходит в контекст модели, поэтому слишком большой результат
сервер не отдаёт — присылает response_too_large с размером и подсказкой.
Данные при этом никогда не обрезаются молча.
Получив такой отказ, сначала решите, нужны ли вам все данные.
Передайте page_size, дальше возвращайте полученный
next_cursor, пока он приходит. Работает при любом объёме и ничего не
теряет.
get_registry(form_id: …, page_size: 150)
→ задачи + next_cursor
get_registry(form_id: …, page_size: 150,
cursor: "…")
→ задачи + next_cursor
→ порция без курсора = конецsummary: true — что это и насколько велико, за килобайтfield_ids, columns — только нужные поляformat: "csv" — без разметки, до 32× компактнееПриёмы складываются: короче строка — больше влезает в порцию.
Размер порции подбирается под ширину строки. Замерено: 300 задач с одним полем весили 196 КБ и упёрлись в потолок, 150 прошли свободно. Начинайте со 150 и делите пополам при отказе — отказ приходит быстро и стоит дёшево.
| Что видите | Что это значит | Что делать |
|---|---|---|
401 |
Токен MCP не принят | Проверьте Authorization: Bearer … и что токен скопирован целиком |
no_credentials |
Не пришли реквизиты Pyrus | Добавьте X-Pyrus-Security-Key рядом с логином — одного логина мало |
response_too_large |
Ответ не влезет в контекст | Обход через page_size, либо сужение — см. раздел выше |
download_too_large |
Pyrus присылал больше порога | item_count, page_size или plan_registry_walk |
register_truncated |
Реестр обрезан Pyrus на 20 000 | plan_registry_walk построит окна по датам |
pyrus_rate_limit |
Выбрана квота аккаунта | Подождать. 5000 запросов за 10 минут, общих на всех |
unknown_endpoint |
Опечатка в пути | Pyrus отвечает на несуществующий маршрут 202, а не 404 — сервер это распознаёт |
Если увидите голое Error executing tool … без объяснения — это старая
версия клиента или посредник, который съел текст. Сервер всегда возвращает поле
error с кодом и человеческим сообщением.
| Ограничение | Порог | Чьё оно |
|---|---|---|
| Задач в реестре формы | 20 000 | Pyrus. Обрезает молча, без всякого признака |
| Размер ответа инструмента | 200 КБ | Сервера. Бережёт контекст модели |
| Размер загрузки от Pyrus | 16 МБ | Сервера. Бережёт его собственную память |
| Запросов к API | 5000 / 10 мин | Pyrus. Общие на весь аккаунт |
Она общая для всех, кто работает под этим аккаунтом. Обход задача-за-задачей выбирает её на первых тысячах, и остальные останутся без квоты. Берите выборкой, а не циклом.