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"
    }
  }
}
  1. Сохраните настройки и начните подключение в клиенте.
  2. В открывшемся браузере войдите в свою учётную запись СУДиДЕЛО. При запросе дополнительного подтверждения выполните его.
  3. Проверьте название приложения и нажмите «Подключить». Кнопка «Отмена» завершает подключение без предоставления доступа.
  4. После успешной авторизации вернитесь в 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 для ИП. Объяснение и сравнение показателей выполняет ИИ-помощник на основе полученной карточки.

Как устроена работа

  1. Вы сообщаете помощнику ИНН и задачу.
  2. Клиент вызывает pb_nalog_poluchit с параметром inn и при необходимости refresh.
  3. Сервер обращается к API СУДиДЕЛО с вашим ключом и получает карточку из кеша либо сведения от портала ФНС.
  4. Клиент получает структурированные данные; помощник разбирает их и формирует ответ.

Первое получение сведений может занимать до 120 секунд на стороне API. Если клиент позволяет настроить таймаут, задайте его с запасом относительно 150 секунд.

Актуальность сведений

Попросите помощника указывать источник и время получения карточки. В meta.source возвращается:

  • portal — сведения получены от портала.
  • cache — использована сохранённая карточка. Время получения указано в meta.fetched_at, срок кеширования — в meta.ttl_hours.
  • stale — портал недоступен, возвращена устаревшая карточка. Сервер дополнительно предупреждает об этом в поле итог.

По умолчанию refresh=false: сервер использует обычные правила кеширования. refresh=true запрашивает обновление, обходя срок кеширования и кеш отсутствующих записей. Даже при таком запросе свежие сведения не гарантируются: при недоступности портала могут вернуться устаревшие данные.

Важные ограничения

  • Поиск по названию, ОГРН или ФИО не предусмотрен — нужен ИНН строкой без пробелов. Начальные нули сохраняйте.
  • Пустое поле, null или отсутствие сведений не означают нулевое значение, отсутствие задолженности либо нарушений.
  • Для ИП часть разделов может отсутствовать или быть пустой.
  • Сервер возвращает карточку данных. Получение PDF-выписки ЕГРЮЛ/ЕГРИП, создание мониторинга и редактирование CRM в его каталог не входят.
  • Доступный инструмент в каталоге ещё не подтверждает право на получение карточки: права проверяются при запросе данных.
  • Ответ помощника зависит от полученных сведений и возможностей клиента. Проверяйте даты, периоды и предупреждения об актуальности.

Если что-то не работает

  1. Проверьте адрес: для браузерного входа используйте /mcp-oauth, для ручного ключа — /mcp. При недоступности основного домена попробуйте запасной.
  2. Откройте проверку процесса /health: ожидается status: ok. Она подтверждает работу процесса, но не проверяет ключ, права и получение карточки.
  3. При входе через браузер завершите подтверждение подключения. При ручной настройке проверьте заголовок и действительность API KEY.
  4. При отказе в доступе проверьте активность сотрудника, организацию и права пользователя на соответствующие разделы СУДиДЕЛО.
  5. Проверьте ИНН и тип параметра refresh: допустимы только логические true и false.
  6. Если карточка не найдена, уточните ИНН. При временном сбое или ограничении частоты повторите запрос позже; при долгом ожидании проверьте таймаут клиента.
  7. После смены домена, замены ключа или перезапуска сервера переподключитесь и начните новую сессию. Для браузерного входа при смене домена авторизуйтесь заново.

Для разработчиков

Транспорт — 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.

Связанные инструкции