Как подключить MCP-сервер к Claude: инструкция на примере проверки контрагентов

Чтобы подключить MCP-сервер к Claude, ему сообщают команду запуска сервера: в Claude Desktop — в файле claude_desktop_config.json (меню Settings → Developer → Edit Config), в Claude Code — командой claude mcp add имя -- команда. После перезапуска Claude видит инструменты сервера и сам решает, когда их вызвать. Разбираем подключение на открытом MCP-сервере KontragentPro, который проверяет российские компании по ИНН: команды, ключ, ошибки и цифры из журнала нашего API за сентябрь–октябрь 2026 года.

MCP-сервер: что это за программа

MCP-сервер — программа, которая даёт ИИ-ассистенту инструменты: поиск по базе, чтение файлов, запросы к внешнему API. Работает она по Model Context Protocol — открытому протоколу, который Anthropic представила в ноябре 2024 года; спецификация и документация лежат на modelcontextprotocol.io. Приложение с моделью (клиент: Claude Desktop, Claude Code, Cursor) получает от MCP-сервера список инструментов с описанием параметров, а модель по ходу разговора выбирает, какой из них вызвать. Локальный MCP-сервер клиент запускает на вашем компьютере как отдельный процесс (транспорт stdio), удалённый доступен по адресу в интернете (транспорт HTTP). На практике это значит одно: для локального сервера на компьютере должна быть среда, в которой он написан.

Сервер для примера: проверка компаний по ИНН

В примерах подключаем MCP-сервер KontragentPro — сервиса проверки российских компаний по открытым реестрам ФНС, Федресурса, Генпрокуратуры и Роспатента. Пакет kontragentpro-mcp опубликован на PyPI, исходный код — на GitHub под лицензией MIT, а в официальном реестре MCP сервер записан как io.github.kontragentpro/kontragentpro-mcp. Инструментов пять; с любым другим сервером меняются только команда запуска и переменные окружения.

Что установить до подключения

Локальный MCP-сервер запускает сам клиент, поэтому до правки настроек на компьютере нужна среда сервера. Серверы на JavaScript запускают через npx — для него нужен Node.js. Серверы на Python запускают через uvx из менеджера пакетов uv: он сам скачивает пакет с зависимостями в изолированное окружение. Сервер KontragentPro написан на Python 3.10+, поэтому команда запуска — uvx kontragentpro-mcp; без uv подойдёт pip install kontragentpro-mcp, тогда в настройках указывают команду kontragentpro-mcp. Проверьте запуск в терминале заранее: работающий stdio-сервер стартует и молча ждёт ввода — так и должно быть.

Подключение MCP-сервера к Claude Desktop

В Claude Desktop MCP-серверы прописывают в файле claude_desktop_config.json. Порядок описан в документации MCP:

• Откройте меню Claude в системной строке (не настройки внутри окна чата), выберите Settings…, вкладку Developer и нажмите Edit Config. Файл лежит в ~/Library/Application Support/Claude/ на macOS и в %APPDATA%\Claude\ на Windows.
• Добавьте сервер в раздел mcpServers, как в примере ниже.
• Полностью закройте приложение (на macOS — Cmd+Q) и запустите снова: пока процесс жив, конфигурация не перечитывается.
• Нажмите «+» в поле ввода, затем Connectors → Manage connectors: в списке появится сервер и его инструменты.

{
  "mcpServers": {
    "kontragentpro": {
      "command": "uvx",
      "args": ["kontragentpro-mcp"],
      "env": { "KONTRAGENTPRO_API_KEY": "ваш_ключ" }
    }
  }
}

Блок env необязателен: без ключа сервер KontragentPro работает анонимно, но с тесным лимитом, о нём ниже. Перед вызовом инструмента Claude Desktop спрашивает разрешение, и это стоит читать: в запросе видно, какой инструмент и с какими параметрами модель хочет вызвать. В Cursor тот же блок с command и args добавляют через Settings → MCP → Add new server.

Подключение в Claude Code: команда claude mcp add

В Claude Code MCP-сервер добавляют одной командой в терминале до начала сессии:

claude mcp add kontragentpro -e KONTRAGENTPRO_API_KEY=ваш_ключ -- uvx kontragentpro-mcp

Всё после разделителя -- — команда запуска сервера, до него — имя и параметры: -e передаёт переменную окружения, -s задаёт область видимости. Проверка — claude mcp list: у работающего сервера статус «✔ Connected», внутри сессии то же показывает команда /mcp. Если сервер уже прописан в Claude Desktop, на macOS и в WSL его переносит команда claude mcp add-from-claude-desktop (документация Claude Code).

Ключ API не кладите в .mcp.json области project: файл уходит в репозиторий вместе с кодом. Для общего сервера команды каждый передаёт свой ключ через -e в своей области local или user.

Ключ и лимиты: почему без ключа второй вопрос получает отказ

Без ключа MCP-сервер KontragentPro работает анонимно — не больше 5 запросов к API в минуту с одного адреса, и на практике это один вопрос; вдобавок на всех анонимных пользователей действует общий лимит. По журналу нашего API с 10 сентября по 7 октября 2026 года клиенты на версии пакета 0.3.0 сделали 483 запроса с 14 адресов. В серии вызовов на один вопрос медиана — 4 запроса подряд, в 39 сериях из 51 вызовов было три и больше: карточка, отчётность, события. Поэтому второй вопрос в ту же минуту упирается в лимит: 28% запросов этой версии получили отказ 429, все они пришлись на три адреса без ключа. С бесплатным ключом лимит — 60 запросов в минуту и 100 в сутки; ключ выдают по адресу почты на странице API для разработчиков, передают его переменной KONTRAGENTPRO_API_KEY.

Пример: как Claude проверяет компанию через MCP

7 октября 2026 года мы поставили пакет kontragentpro-mcp 0.3.0 из PyPI в чистое окружение, подключили его к Claude Code и задали модели Claude Haiku 4.5 вопрос: «Проверь контрагента с ИНН 7712040126 и покажи динамику выручки за последние годы». Модель вызвала два инструмента, get_company и get_company_financials, и примерно через 10 секунд ответила таблицей. ПАО «Аэрофлот» действует, в реестре банкротств не значится, в карточке стоит отметка о санкционных списках; выручка по отчётности ГИР БО — 760,4 млрд ₽ за 2025 год против 712,9 млрд ₽ за 2024-й, чистая прибыль — 123,0 млрд ₽, капитал — 26,7 млрд ₽ при активах 934,0 млрд ₽. Все числа модель взяла из ответа сервера, а не из своих знаний: в выводе Claude Code вызовы помечены именем сервера, и каждую цифру можно сверить с первоисточником.

Тысячи или миллионы: на чём ошибается модель

В бухгалтерской отчётности, которую налоговая публикует в ГИР БО, суммы указаны в тысячах рублей, а в открытых наборах ФНС о доходах и расходах — в рублях. Модель этого не знает и читает число 760 401 133 как рубли. В первом прогоне того же вопроса Claude написал «выручка 760,4 млн рублей» — ошибка в тысячу раз, хотя сервер отдал верные данные. Пометка единиц в ответе API помогла наполовину: модель подписала таблицу «тыс. руб.», но в строках оставила «760,401 млн». Сработали только готовые подписи вида «760,4 млрд ₽» рядом с сырыми числами — их модель переносит без пересчёта; с 7 октября API отдаёт их в поле readable. Если подключаете MCP-сервер с финансовыми данными, сверяйте порядок чисел в ответе модели с отчётностью компании на bo.nalog.gov.ru.

Когда финансов нет: закрытая отчётность

Иногда инструмент отчётности возвращает пустой ответ, и Claude так и пишет: данных нет. Это не обязательно сбой. С 1 января 2023 года организация вправе подать в налоговую заявление и закрыть доступ к своей отчётности в ГИР БО, если она, в частности, входит в реестр оборонно-промышленного комплекса или перечень стратегических предприятий, попала под иностранные санкции или под угрозу их введения (постановление Правительства № 1624 от 16.09.2022). Из семи крупных компаний, которые мы проверили 7 октября 2026 года, у трёх отчётность в ГИР БО не найдена. Пустой ответ по крупной компании сам по себе не признак риска; у небольшой организации без таких оснований это повод запросить отчётность напрямую.

Если сервер не подключается: частые ошибки

Чаще всего MCP-сервер не подключается по одной из трёх причин. Первая — пропущенный разделитель -- в claude mcp add: Claude Code сохраняет неверную команду, и сервер не стартует. Вторая — сервер подключился, но инструментов нет: обычно ему не хватает переменной окружения, например ключа. Третья — первый запуск дольше 30 секунд, пока uvx или npx скачивает пакет; лимит поднимают переменной MCP_TIMEOUT=60000. Логи Claude Desktop лежат в ~/Library/Logs/Claude на macOS и в %APPDATA%\Claude\logs на Windows, вывод конкретного сервера — в файле mcp-server-ИМЯ.log. И закрепляйте версию, если сервер нужен в работе: наш пакет собирался под библиотеку mcp 1.x, а в версии 2.x модуль mcp.server.fastmcp исчез, и сервер без верхней границы зависимости перестал запускаться. Мы поймали это до публикации в августе 2026 года; версию фиксирует команда uvx kontragentpro-mcp@0.3.0.

Безопасность: что может MCP-сервер и что пробуют с ним сделать

Локальный MCP-сервер работает с правами вашей учётной записи — так прямо сказано в документации MCP, поэтому ставьте серверы из открытых источников, где видно код. Риск есть и в обратную сторону: в журнале нашего API 25 сентября 2026 года за одну минуту прошёл 21 вызов через MCP-пакет, где вместо ИНН передан путь к файлу /root/.mcp_traversal_canary_….txt в семи вариантах кодировки, от %2e%2e%2f до полноширинных точек и невидимых пробелов. Так автоматические сканеры проверяют, не выпустит ли инструмент запрос за пределы API. Все 21 получили ответ 404; наш пакет передаёт параметр как есть, а отсекает его API. Если пишете свой MCP-сервер, проверяйте формат параметров до запроса — для ИНН это 10 или 12 цифр.

Тот же доступ без ИИ: API проверки контрагентов

MCP-сервер KontragentPro — тонкая обёртка над REST API: каждый инструмент соответствует одному методу. Для интеграции с CRM, 1С или собственным скорингом удобнее обращаться к API напрямую: GET /api/v2/companies/{ИНН} возвращает карточку компании с источником каждого блока, /financials — отчётность по годам с подписью единиц, /timeline — события. Ключ тот же, его передают в заголовке Authorization: Bearer. Справочник методов и спецификация OpenAPI — на странице API для разработчиков, описание инструментов и установка — на странице MCP-сервера. Что смотреть в карточке компании без ИИ, разобрано в руководстве «Как проверить контрагента по ИНН».

curl -H "Authorization: Bearer ваш_ключ" \
  https://kontragentpro.ru/api/v2/companies/7712040126/financials

Разбираем, что видно о компаниях по открытым реестрам, в телеграм-канале @kontragentpro.

Команды и пути — по документации Claude Code и Model Context Protocol на 7 октября 2026 года; интерфейс приложений может меняться. Статистика вызовов — журнал API KontragentPro с 10 сентября по 7 октября 2026 года. Данные о компаниях — ЕГРЮЛ, ГИР БО и открытые данные ФНС, ЕФРСБ, ЕРКНМ. Материал не является юридической консультацией.