MCP-сервер для «Прозрачного бизнеса» по ИНН — pb.nalog.ru
MCP-сервер СУДиДЕЛО для «Прозрачного бизнеса» позволяет получать сведения об организации или индивидуальном предпринимателе по ИНН через ИИ-помощника. Подключите сервер к совместимому MCP-клиенту и попросите проверить контрагента или разобрать его показатели.
Источник сведений — сервис ФНС России «Прозрачный бизнес» (pb.nalog.ru). MCP-сервер получает карточку через API СУДиДЕЛО. Предварительно добавлять организацию или ИП в мониторинг не требуется.
Что можно делать
- Получать карточку организации по 10-значному ИНН или ИП по 12-значному ИНН.
- Просматривать доступные реквизиты, адрес, статус, сведения о руководителях, участниках и видах деятельности ОКВЭД.
- Разбирать доступные финансовые показатели, численность работников, уплаченные налоги, задолженность, нарушения и налоговые режимы.
- Просить помощника объяснить сведения и сравнить имеющиеся показатели по годам.
- Запрашивать обновление карточки и проверять источник и время получения данных.
В каталоге сервера один инструмент — pb_nalog_poluchit. В чате достаточно описать задачу своими словами. Состав сведений зависит от карточки и данных, доступных через API; одинаковое заполнение всех разделов для организаций и ИП не гарантируется.
Что нужно для начала
- Учётная запись СУДиДЕЛО, активный сотрудник и организация, а также доступ хотя бы к одному из разделов: юридические лица, индивидуальные предприниматели или результаты мониторинга ЕГРЮЛ.
- MCP-клиент с поддержкой Streamable HTTP. Для входа через браузер нужна поддержка такого способа авторизации, для ручной настройки — пользовательских HTTP-заголовков.
- При ручной настройке — API KEY пользователя из раздела «Интеграция → API». При входе через браузер копировать ключ не требуется. Подробнее — на странице API СУДиДЕЛО.
Сервер работает удалённо: устанавливать Python или разворачивать сервер на своём компьютере не нужно.
Какой адрес выбрать
На обоих адресах доступны одни и те же сведения, вход через браузер и подключение по API KEY.
- Для работы из зарубежных сервисов используйте основной домен
mcp-pb-nalog.torkndgov.ru. - Для работы из России можно использовать запасной домен
mcp-pb-nalog-ru.torkndgov.ru. Если основной адрес недоступен из вашей сети, попробуйте этот адрес.
Учитывайте место работы клиента или онлайн-сервиса, который подключается к MCP. API KEY один и тот же для обоих адресов. При смене домена создайте новое подключение; для входа через браузер пройдите авторизацию заново.
Адреса подключения
- Вход через браузер:
https://mcp-pb-nalog.torkndgov.ru/mcp-oauth - Вход через браузер на запасном адресе:
https://mcp-pb-nalog-ru.torkndgov.ru/mcp-oauth - Основной адрес по API KEY:
https://mcp-pb-nalog.torkndgov.ru/mcp - Запасной адрес по API KEY:
https://mcp-pb-nalog-ru.torkndgov.ru/mcp - Проверка процесса: основной адрес и запасной адрес.
Подключение в агенте ИИ
Способ 1. Войти через браузер
В совместимом MCP-клиенте добавьте удалённый сервер с адресом, заканчивающимся на /mcp-oauth. Пример конфигурации для адреса из России:
{
"mcpServers": {
"sudodelo-pb-nalog": {
"url": "https://mcp-pb-nalog-ru.torkndgov.ru/mcp-oauth"
}
}
}
- Сохраните настройки и начните подключение в клиенте.
- В открывшемся браузере войдите в свою учётную запись СУДиДЕЛО. При запросе дополнительного подтверждения выполните его.
- Проверьте название приложения и нажмите «Подключить». Кнопка «Отмена» завершает подключение без предоставления доступа.
- После успешной авторизации вернитесь в MCP-клиент и убедитесь, что доступен инструмент
pb_nalog_poluchit.
Для основного адреса замените значение url на https://mcp-pb-nalog.torkndgov.ru/mcp-oauth. Ключ не нужно вводить в чат или аргументы инструмента. При выпуске сервера проверен полный HTTP-цикл браузерного входа на обоих адресах; подключение именно этого сервера через интерфейс LM Studio отдельно не проверялось.
Способ 2. Указать API KEY вручную
В настройках MCP-клиента укажите адрес с окончанием /mcp и заголовок X-Sudodelo-Api-Key. Вместо плейсхолдера вставьте свой ключ:
{
"mcpServers": {
"sudodelo-pb-nalog": {
"url": "https://mcp-pb-nalog.torkndgov.ru/mcp",
"headers": {
"X-Sudodelo-Api-Key": "YOUR_API_KEY"
}
}
}
}
Для запасного адреса используйте https://mcp-pb-nalog-ru.torkndgov.ru/mcp с тем же ключом. Сохраните настройки и переподключите сервер. Точный формат конфигурации зависит от клиента.
Как передать ключ доступа
При входе через браузер приложение получает доступ после вашего подтверждения. При ручной настройке ключ передаётся в заголовке каждого запроса. Передавать его помощнику сообщением или добавлять в аргументы инструмента не требуется.
Оба способа используют существующий ключ пользователя и его права. Подключайте приложения, которым готовы предоставить этот доступ. Замена или отзыв ключа прекращает работу старого ключа во всех подключениях, где он использовался: обновите ручные настройки или заново подключитесь через браузер. Обычный выход из аккаунта в браузере сам по себе не отзывает ключ.
Примеры запросов в чате
- «Получи сведения из „Прозрачного бизнеса“ по ИНН 7707083893. Покажи реквизиты, руководителей и виды деятельности».
- «Проверь организацию по ИНН [ИНН организации]: какие сведения о налогах и задолженности доступны?»
- «Получи карточку ИП по ИНН [ИНН предпринимателя] и перечисли доступные сведения».
- «Сравни имеющиеся показатели по годам и укажи периоды, за которые данных нет».
- «Запроси обновление карточки по ИНН [ИНН] с refresh=true. Укажи источник и время получения данных; предупреди, если возвращены устаревшие сведения».
Замените текст в квадратных скобках настоящим ИНН: 10 цифр для организации или 12 для ИП. Объяснение и сравнение показателей выполняет ИИ-помощник на основе полученной карточки.
Как устроена работа
- Вы сообщаете помощнику ИНН и задачу.
- Клиент вызывает
pb_nalog_poluchitс параметромinnи при необходимостиrefresh. - Сервер обращается к API СУДиДЕЛО с вашим ключом и получает карточку из кеша либо сведения от портала ФНС.
- Клиент получает структурированные данные; помощник разбирает их и формирует ответ.
Первое получение сведений может занимать до 120 секунд на стороне API. Если клиент позволяет настроить таймаут, задайте его с запасом относительно 150 секунд.
Актуальность сведений
Попросите помощника указывать источник и время получения карточки. В meta.source возвращается:
portal— сведения получены от портала.cache— использована сохранённая карточка. Время получения указано вmeta.fetched_at, срок кеширования — вmeta.ttl_hours.stale— портал недоступен, возвращена устаревшая карточка. Сервер дополнительно предупреждает об этом в полеитог.
По умолчанию refresh=false: сервер использует обычные правила кеширования. refresh=true запрашивает обновление, обходя срок кеширования и кеш отсутствующих записей. Даже при таком запросе свежие сведения не гарантируются: при недоступности портала могут вернуться устаревшие данные.
Важные ограничения
- Поиск по названию, ОГРН или ФИО не предусмотрен — нужен ИНН строкой без пробелов. Начальные нули сохраняйте.
- Пустое поле,
nullили отсутствие сведений не означают нулевое значение, отсутствие задолженности либо нарушений. - Для ИП часть разделов может отсутствовать или быть пустой.
- Сервер возвращает карточку данных. Получение PDF-выписки ЕГРЮЛ/ЕГРИП, создание мониторинга и редактирование CRM в его каталог не входят.
- Доступный инструмент в каталоге ещё не подтверждает право на получение карточки: права проверяются при запросе данных.
- Ответ помощника зависит от полученных сведений и возможностей клиента. Проверяйте даты, периоды и предупреждения об актуальности.
Если что-то не работает
- Проверьте адрес: для браузерного входа используйте
/mcp-oauth, для ручного ключа —/mcp. При недоступности основного домена попробуйте запасной. - Откройте проверку процесса
/health: ожидаетсяstatus: ok. Она подтверждает работу процесса, но не проверяет ключ, права и получение карточки. - При входе через браузер завершите подтверждение подключения. При ручной настройке проверьте заголовок и действительность API KEY.
- При отказе в доступе проверьте активность сотрудника, организацию и права пользователя на соответствующие разделы СУДиДЕЛО.
- Проверьте ИНН и тип параметра
refresh: допустимы только логическиеtrueиfalse. - Если карточка не найдена, уточните ИНН. При временном сбое или ограничении частоты повторите запрос позже; при долгом ожидании проверьте таймаут клиента.
- После смены домена, замены ключа или перезапуска сервера переподключитесь и начните новую сессию. Для браузерного входа при смене домена авторизуйтесь заново.
Для разработчиков
Транспорт — Streamable HTTP. Инструмент pb_nalog_poluchit выполняет запрос чтения. Пример аргументов:
{"inn": "7707083893", "refresh": false}
inn— обязательная строка из 10 или 12 ASCII-цифр; контрольная сумма на уровне MCP не проверяется.refresh— необязательное логическое значение, по умолчаниюfalse. Строки, числа иnullне принимаются.
Успешный результат содержит итог, разрешено: true и объект данные. В карточке находятся inn, type (organization или individual), subject, meta и доступные массивы: managers, participants, okved2_exs, form1, sschr, taxpay, offense, arrear, taxmode. Имена полей и значения JSON API сохраняются.
При прикладном отказе возвращаются разрешено: false и сообщение в итог, без данные. Проверяйте это поле: MCP isError при таком отказе может быть false. Неверная форма аргументов возвращается как MCP-ошибка до запроса к API.