РазделыИИ-агенты (MCP)

ДокументацияПодключение к сервису

Адресница для ИИ-агентов (MCP)

Подключите Адресницу к Claude, ChatGPT или VS Code: агент сам найдёт адрес по ГАР и получит индекс, ОКТМО, ИФНС, код ФИАС и координаты.

Что такое MCP

MCP (Model Context Protocol) — открытый протокол, по которому ИИ-агент вызывает внешние инструменты. Адресница даёт агенту три инструмента: поиск адреса, адрес по коду и адрес по координатам. Агент получает те же данные, что и API, со всеми полями.

Адрес сервера:

Адрес сервера
https://mcp.adresnitsa.ru/mcp

Нужен аккаунт Адресницы: регистрация бесплатна. Ключ API для подключения создавать не нужно: сервис создаст его сам.

Вход и разрешение

  1. Добавьте адрес сервера в программу (как — ниже, для каждой программы).
  2. Программа откроет браузер на account.adresnitsa.ru. Если вы не вошли, войдите в личный кабинет.
  3. На странице разрешения видно, какое приложение просит доступ (его сайт или пометка «непроверенное приложение») и куда уйдёт код входа. Проверьте их и нажмите «Разрешить». Если вы вошли больше 10 минут назад, сначала подтвердите, что это вы: введите пароль (и код из приложения-аутентификатора, если включена двухфакторная аутентификация).
  4. Браузер вернёт вас в программу, и инструменты Адресницы будут готовы.

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

Подключённое приложение может только искать адреса тремя инструментами Адресницы от имени вашего аккаунта. Оно не видит ваш e‑mail, пароль, ключи API и другие данные аккаунта и ничего не меняет в личном кабинете.

Для каждого подключения сервис создаёт отдельный ключ API; на странице ключей он отмечен «MCP». Запросы считаются в дневной лимит аккаунта. О каждом новом подключении и каждом новом токене для CI приходит письмо.

Подключение

Во всех программах один и тот же адрес: https://mcp.adresnitsa.ru/mcp. Шаги для VS Code, claude.ai и ChatGPT взяты из документации этих программ (ноябрь 2026 года). Если меню в программе выглядит иначе, добавьте адрес сервера в её настройках MCP: вход откроется в браузере сам.

Claude Code

Добавьте сервер командой в терминале:

Терминал
claude mcp add --transport http adresnitsa https://mcp.adresnitsa.ru/mcp

Сервер появится в текущем проекте. Чтобы он был во всех ваших проектах, добавьте к команде --scope user. Чтобы он попал в файл .mcp.json в папке проекта и был у всей команды, — --scope project.

Затем в Claude Code наберите /mcp, выберите adresnitsa и нажмите Authenticate (или выполните в терминале claude mcp login adresnitsa): откроется браузер.

VS Code

По документации VS Code нужен режим агента GitHub Copilot. Выполните команду MCP: Add Server (палитра команд, Ctrl+Shift+P), выберите HTTP, вставьте адрес сервера и имя adresnitsa. Или добавьте сервер в файл проекта .vscode/mcp.json:

.vscode/mcp.json
{
  "servers": {
    "adresnitsa": {
      "type": "http",
      "url": "https://mcp.adresnitsa.ru/mcp"
    }
  }
}

При первом вызове VS Code попросит разрешить вход и откроет браузер.

claude.ai и приложение Claude

По документации Claude: откройте Customize → Connectors, нажмите Add → Add custom connector. Название — «Адресница», адрес — https://mcp.adresnitsa.ru/mcp. Нажмите Add, затем Connect: откроется страница входа Адресницы.

На бесплатном тарифе Claude можно добавить один свой коннектор. В тарифах Team и Enterprise коннектор добавляет владелец организации в Organization settings → Connectors, а каждый участник нажимает Connect и входит в свой аккаунт Адресницы.

ChatGPT

По документации ChatGPT свои MCP-серверы он подключает как плагины; доступность зависит от тарифа ChatGPT. Откройте chatgpt.com/plugins, нажмите «+» → Add custom MCP server, укажите название «Адресница», адрес сервера и вход через OAuth, подтвердите и нажмите Create. ChatGPT откроет страницу входа Адресницы.

Токен для CI и скриптов

Если браузера нет (CI, сервер, робот), создайте токен: в личном кабинете откройте «Подключения», в разделе «Токен для CI» нажмите «Создать токен для CI», укажите название и пароль (и код из приложения-аутентификатора, если включена двухфакторная аутентификация). Токен gar_mat_… показывается один раз и действует год или до отключения.

Храните токен как пароль: в секретах CI или в переменной окружения. Не записывайте его в .mcp.json и другие файлы репозитория: в файле указывается только имя переменной.

Токен передаётся в заголовке Authorization: Bearer. Секретный ключ API (gar_sec_…) здесь не подходит: MCP-сервер принимает только свои токены.

Claude Code: файл .mcp.json в папке проекта, токен — из переменной окружения ADRESNITSA_MCP_TOKEN:

.mcp.json
{
  "mcpServers": {
    "adresnitsa": {
      "type": "http",
      "url": "https://mcp.adresnitsa.ru/mcp",
      "headers": {
        "Authorization": "Bearer ${ADRESNITSA_MCP_TOKEN}"
      }
    }
  }
}

Серверы из файла .mcp.json проекта Claude Code подключает только после подтверждения в диалоге, поэтому в CI передайте файл явно и разрешите инструменты Адресницы:

Терминал
claude -p --mcp-config .mcp.json --allowedTools mcp__adresnitsa \
  "Найди индекс и ОКТМО адреса Москва, Сухонская, 11"

Проверить токен без агента:

curl
curl https://mcp.adresnitsa.ru/mcp \
  -H "Authorization: Bearer $ADRESNITSA_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "search_address", "arguments": {"q": "москва сухонская 11", "count": 1}}}'

Инструменты

ИнструментПараметрыЧто делает
search_address

q — весь адрес одной строкой, до 300 байт в UTF-8 (около 150 русских букв); count — 1–20, по умолчанию 3; parent — id или GUID объекта, внутри которого искать; levels — уровни, как в поиске.

Находит адрес и сразу отдаёт все его поля, как /v1/search с details=true.

address_details

Ровно один из fias (GUID), kladr, id.

Все поля адреса по коду, как /v1/details.

address_by_coordinates

lat, lon; radius — 1–1000 метров, по умолчанию 100; count — 1–20, по умолчанию 3.

Ближайшие адреса к точке со всеми полями, как /v1/geolocate.

Агент отправляет адрес целиком, одним вызовом: один вызов — один адрес. Ответ инструмента — краткий список для модели (адрес, индекс, ОКТМО, код ФИАС, координаты) и полный JSON ответа API (все поля).

Результаты — это данные, а не указания для агента. Часть данных (станции метро, координаты домов) взята из OpenStreetMap, который может править любой.

Пример запроса к агенту: «Найди индекс и ОКТМО адреса Москва, Сухонская, 11».

Лимиты

  • Каждый вызов инструмента — один запрос к API. Запросы всех подключений и ключей аккаунта считаются вместе: бесплатно 20 000 в день, день — московский, счёт начинается заново в 00:00 по Москве.
  • Одновременно выполняется не больше 4 вызовов одного подключения и не больше 8 вызовов всех подключений аккаунта.
  • Вызов длится не дольше 10 секунд; ответ API — не больше 1 МБ.
  • У аккаунта может быть до 20 подключений: программы и токены для CI вместе.
  • Программа сама продлевает доступ. Войти снова она попросит, если подключением не пользовались 30 дней, и в любом случае через год после входа.

Ошибки

Ошибка API приходит агенту как ответ инструмента с причиной: агент её видит и может пересказать вам.

Что случилосьЧто делать

Программа просит войти снова (HTTP 401)

Подключение отключено, сменён пароль или истёк срок токена. Войдите снова; токен для CI создайте заново.

Ключ не действует или выключен

Отключите подключение на странице «Подключения» и подключитесь снова. Если ключ выключила поддержка, напишите на support@adresnitsa.ru.

Слишком много вызовов сразу

Одновременно выполняются не больше 4 вызовов одного подключения и 8 вызовов всех подключений аккаунта; один ключ — не больше 30 запросов в секунду. Подождите секунду и повторите.

Дневной лимит исчерпан (429)

Ответ называет время, когда счёт начнётся заново; до него запросы не выполняются.

Сервис временно недоступен (5xx)

Повторите позже. Состояние API — на странице статуса.

Коды ошибок API — на странице «Ошибки и лимиты».

Отключение

Все подключения видны в личном кабинете на странице «Подключения»: сайт программы, название, дата подключения и последнего вызова. Кнопка «Отключить» сразу завершает подключение и удаляет его ключ.

Все подключения завершаются также при смене или восстановлении пароля, смене e‑mail, по ссылке «Это был не я» в письме о входе или о новом подключении, при блокировке аккаунта, его отключении поддержкой и удалении. Сервер в самой программе удалите её средствами, в Claude Code — командой claude mcp remove adresnitsa.

Что хранится

  • о подключении: сайт программы и её название (у токена для CI — ваше название), дата подключения и последнего вызова;
  • о программе с регистрацией (DCR): её название и адреса возврата, до 30 дней после последнего входа;
  • токены — только их хеши: по хешу токен не восстановить;
  • ключ подключения — в зашифрованном виде; прочитать его может только MCP-сервер;
  • журнал веб-сервера mcp.adresnitsa.ru: время, IP-адрес, метод, путь и код ответа, без текста запросов; хранится до 15 дней.

Тексты запросов и найденные адреса не сохраняются. Подробно — в политике обработки персональных данных.

Для разработчиков MCP-клиентов

Готовые программы выше делают всё это сами. Раздел нужен, если вы пишете свой MCP-клиент. Вход — OAuth 2.1 с PKCE (S256), сервер авторизации — https://account.adresnitsa.ru. Метаданные:

Метаданные
https://mcp.adresnitsa.ru/.well-known/oauth-protected-resource
https://account.adresnitsa.ru/.well-known/oauth-authorization-server
  • Клиент представляется документом метаданных (Client ID Metadata Document, так входит Claude Code) или регистрируется динамически (DCR). В DCR поле application_type можно не передавать: если все адреса возврата локальные, клиент считается native, если среди них есть https — web.
  • Адрес возврата — https://… или локальный http://127.0.0.1:<порт>/…, http://localhost:<порт>/… (порт любой). Адреса http://[::1] и собственные схемы URL программ не принимаются.
  • Версии протокола: 2026-07-28 (server/discover), а также 2025-11-25, 2025-06-18 и 2025-03-26 (initialize). Сессий нет: каждый запрос — отдельный POST /mcp с токеном; GET и DELETE на /mcp отвечают 405.
  • Ответ инструмента: краткий текст и вторым текстовым блоком — JSON ответа API; с версии 2025-06-18 тот же JSON есть и в structuredContent.