ДокументацияПодключение к сервису
Адресница для ИИ-агентов (MCP)
Подключите Адресницу к Claude, ChatGPT или VS Code: агент сам найдёт адрес по ГАР и получит индекс, ОКТМО, ИФНС, код ФИАС и координаты.
Что такое MCP
MCP (Model Context Protocol) — открытый протокол, по которому ИИ-агент вызывает внешние инструменты. Адресница даёт агенту три инструмента: поиск адреса, адрес по коду и адрес по координатам. Агент получает те же данные, что и API, со всеми полями.
Адрес сервера:
https://mcp.adresnitsa.ru/mcp
Нужен аккаунт Адресницы: регистрация бесплатна. Ключ API для подключения создавать не нужно: сервис создаст его сам.
Вход и разрешение
- Добавьте адрес сервера в программу (как — ниже, для каждой программы).
- Программа откроет браузер на
account.adresnitsa.ru. Если вы не вошли, войдите в личный кабинет. - На странице разрешения видно, какое приложение просит доступ (его сайт или пометка «непроверенное приложение») и куда уйдёт код входа. Проверьте их и нажмите «Разрешить». Если вы вошли больше 10 минут назад, сначала подтвердите, что это вы: введите пароль (и код из приложения-аутентификатора, если включена двухфакторная аутентификация).
- Браузер вернёт вас в программу, и инструменты Адресницы будут готовы.
Пароль спрашивается по той же причине, что и при создании секретного ключа: подключение получает доступ к 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:
{
"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:
{
"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 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 |
| Находит адрес и сразу отдаёт все его поля, как /v1/search с |
| address_details | Ровно один из | Все поля адреса по коду, как /v1/details. |
| address_by_coordinates |
| Ближайшие адреса к точке со всеми полями, как /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.