О деньгах всё чаще спрашивают универсального ИИ-ассистента. «Сколько мы потратили на продукты в прошлом месяце?», «какие бюджеты превышены?» — вопросы простые, но Claude или ChatGPT не ответят на них без данных. Пользователю AI Budget до сих пор приходилось выгружать данные или переписывать цифры в чат вручную.

Мы закрыли этот разрыв MCP-коннектором. Любой ассистент, который умеет работать с удалёнными MCP-серверами, теперь может подключиться к https://api.ai-budget.pl/mcp, спросить разрешения у пользователя на нашей собственной странице согласия и читать его расходы, доходы, категории и бюджеты. В статье — зачем мы это сделали, почему это заняло всего несколько дней и что нашли ревью, прежде чем мы включили коннектор 13 ноября 2026 года.

Почему MCP и почему сейчас

MCP (Model Context Protocol) — открытый стандарт подключения ИИ-ассистентов к внешним инструментам и данным. Ассистенту не нужна интеграция, написанная специально под него: он получает от сервера список инструментов и вызывает их, когда вопрос того требует. Поэтому один сервер работает и с Claude, и с ChatGPT, и с любым другим клиентом, который знает протокол.

Для нас это было дёшево по причине, которую мы подготовили заранее. У AI Budget уже было публичное API — это интерфейс, через который две системы обмениваются данными автоматически, без выгрузок в Excel и копирования руками. Полное определение → со своим OAuth-сервером — мы описывали его в предыдущей статье. Авторизация, экран согласия, доступ по счетам, маскирование полей и лимиты запросов существовали и работали в проде. MCP-коннектор — второй вход к тем же данным, а не новая система.

Причин было три:

Пользователи. Спросить ассистента о собственном бюджете — естественно, а переписывать цифры вручную — ровно противоположное тому, для чего существует приложение.

Охват. «Работает с Claude и ChatGPT» — короткая и честная история, а каталоги коннекторов — канал, которого у нас не было.

Проверка. Это первый настоящий сквозной прогон нашего OAuth в проде — код, Токен — это фрагмент текста, обычно часть слова: ИИ-модели измеряют в токенах и длину запроса, и стоимость, поэтому счёт приходит за токены, а не за вопросы. Полное определение →, вызов, обновление, отзыв — силами клиентов, которых писали не мы.

Решения владельца рано зафиксировали рамки: подключиться может любой MCP-клиент, доступ только на чтение, а ассистент видит ровно то, что отдаёт публичное API, — не больше. Запись, фото чеков и локальный (stdio) пакет сервера сознательно не вошли.

Как ассистент находит нас без API-ключа

Пользователь вводит один адрес. Остальное ассистент находит сам, по уже существующим стандартам:

1. Ответ 401, который объясняет, что делать. Первый вызов /mcp идёт без токена, поэтому сервер отвечает 401 с заголовком WWW-Authenticate, указывающим на /.well-known/oauth-protected-resource/mcp (RFC 9728).

2. Метаданные. Этот документ называет наш сервер авторизации, а /.well-known/oauth-authorization-server (RFC 8414) перечисляет адреса, поддерживаемые области доступа и единственный разрешённый метод PKCE — S256.

3. Саморегистрация. Ассистент сам регистрируется на /oauth/register (Dynamic Client Registration, RFC 7591). Он становится публичным клиентом: без секрета, с обязательным PKCE, с пометкой «зарегистрирован ассистентом».

4. Согласие. Браузер открывает app.ai-budget.pl/authorize — ту же страницу, что и для любого подключённого приложения. Пользователь входит, отмечает счета, которые ассистент может читать, и подтверждает.

5. Токен и вызовы. Ассистент обменивает код на токен и вызывает инструменты на /mcp. Обновлённый токен остаётся привязан к тому же ресурсу.

Девять инструментов только на чтение

Сервер отдаёт девять инструментов: list_accounts, list_expenses, get_expense, list_incomes, get_income, list_categories, list_budgets, get_budget и get_spending_summary. Они покрывают то, что читает публичное API: счета, расходы и доходы с фильтрами и деталями, категории расходов и доходов, бюджеты с прогрессом за текущий период и суммы трат.

Результаты ограничены намеренно. Список принимает limit от 1 до 200 (по умолчанию 50) и курсор, ни один результат не превышает 200 строк, а расход, в чеке которого больше 200 позиций, прямо пишет «Showing 200 of N», а не делает вид, что показал всё. Фото чеков через MCP нет совсем: они большие и мало что дают чат-модели.

Эндпоинт работает внутри нашего API на NestJS, на официальном TypeScript SDK для MCP, в транспорте Streamable HTTP. Он без состояния — один экземпляр сервера на запрос, — потому что инструментам чтения сессия не нужна.

Одно ядро авторизации для REST и MCP

Главное правило проекта — запрет: у MCP нет отдельной авторизации. Прежде чем писать коннектор, мы вынесли логику защитника публичного API в один сервис, PublicApiAuthorizer, и закрепили его поведение тестами. Его вызывают и REST-защитник, и /mcp; изменение авторизации меняет обе поверхности сразу.

Он читает базу при каждом вызове и ничего не кэширует: токен, не отозван ли доступ, не заблокировано ли приложение, активен ли пользователь, остаётся ли выдавший доступ владельцем или редактором этого счёта, и уровень шифрования счёта. Отключение ассистента в приложении, блокировка администратором или понижение до наблюдателя останавливают его на следующем же вызове инструмента.

Правила данных те же, что для любого подключённого приложения. Счёт с полным сквозным шифрованием не читается вообще, а на счёте с шифрованием текстов зашифрованные поля остаются скрыты. Каждый инструмент читает через те же функции представления, что и REST-контроллеры, а не собственным запросом.

Токен работает ровно на одной поверхности

OAuth-токен говорит, кто и что может делать, но не где. Это мы добавили через индикаторы ресурса (RFC 8707): токен несёт ресурс, для которого выдан. Токен для /mcp отвергается REST API, а REST-токен — /mcp.

Для саморегистрирующихся клиентов это важно: ассистент, который зарегистрировался сам, обязан назвать ресурс MCP, поэтому может держать только MCP-токены. Анонимная регистрация никогда не доберётся до REST API, у которого иначе могла бы запросить области записи.

По той же причине ограничены области доступа. Саморегистрирующемуся ассистенту доступны только expenses:read, categories:read, incomes:read, budgets:read и analytics:read. receipts:read и любые области записи отвергаются при авторизации, обмене кода и обновлении.

Одну тонкость мы записали как правило: /mcp только на чтение из-за набора инструментов, а не из-за проверки области — приложение, зарегистрированное разработчиком, может иметь области записи и MCP-токен. Поэтому добавить инструмент записи — это не «просто зарегистрировать инструмент»: такое изменение требует решения об областях, типах клиентов и подтверждении.

Что нашли ревью

До запуска код прошёл несколько волн ревью. Большинство замечаний касались саморегистрации и экрана согласия, потому что именно там неизвестная сторона может поставить что-то перед нашими пользователями.

Злоупотребление регистрацией. Первый лимит считался по IP-адресу. Ревью указало, что в IPv6 одна машина может перебирать адреса во всём префиксе /64, поэтому теперь лимит считается по /64, а сверху есть глобальный потолок — 300 регистраций в час. Если Redis недоступен, регистрация получает 429, а не становится безлимитной; тело запроса ограничено 16 КБ.

Выдача себя за нас на нашем же экране согласия. Ассистент сам называет себя, так что регистрация могла бы назваться как наш продукт. Имя, содержащее название продукта, отвергается — без учёта регистра, диакритики и пробелов, с небольшой картой похожих символов, а также название нашей компании и польское и русское слово «бюджет».

Доверие к тому, что клиент заявил о себе сам. Всё в регистрации пишет тот, кто регистрируется. Поэтому экран согласия показывает имя простым текстом без bidi-символов, символов нулевой ширины и управляющих, заявленную домашнюю страницу — только хостом в punycode и без ссылки, а логотип — никогда: его загрузка отправила бы IP-адрес смотрящего тому, кто зарегистрировался. Вместо этого в рамке предупреждения он показывает единственный факт, который не является заявлением: «Доступ будет отправлен на <host>», взятый из проверенного адреса перенаправления, так что похожий домен выглядит как xn--….

Стоимость запроса. Лимит считает одну единицу на вызов инструмента, в тех же корзинах, что и REST API. Проверка соединения перед вызовом не считается — это сознательная поправка, иначе каждый вызов стоил бы вдвое. Тело /mcp ограничено 128 КБ ещё до аутентификации — глобальный парсер принял бы 50 МБ, — а пакеты JSON-RPC отвергаются: версия протокола 2025-06-18 убрала пакетные запросы, а пакет умножал бы стоимость одной единицы.

Скрытый маршрут должен оставаться скрытым. Всё выкатывается за двумя флагами, и пока они выключены, /mcp, регистрация и документы обнаружения отвечают 404. Ревью заметило, что парсеры тела для этих маршрутов работают раньше любого защитника и отвечали бы 400 или 413 — выдавая маршрут, который должен быть невидим. Теперь они проверяют флаг на каждом запросе.

Не сломать существующих клиентов. Клиент публичного API, следующий спецификации, тоже может назвать свой ресурс. Такие идентификаторы означают REST API, поэтому привязка токенов к ресурсам никого из уже подключённых не сломала.

Уборка и логи. Саморегистрирующиеся клиенты, которыми никто не пользуется, мягко удаляются через 30 дней после последнего доступа. В логах MCP — имя инструмента, результат и длительность, но никогда токен, код или финансовая строка; при внутренней ошибке добавляется только имя класса ошибки.

Включение

13 ноября 2026 года мы добавили два блока в общий nginx — /mcp и документы обнаружения в зоне лимитов публичного API, с маленьким ограничением тела, — мягко перезагрузили его и включили флаг. До флага проверили, что новые пути доходят до API и отвечают 404 от API, а не от nginx; после — что документы обнаружения отвечают, а /mcp возвращает 401 с правильным заголовком.

Первый настоящий клиент нашёл то, чего не нашло ни одно ревью. Claude Code регистрируется под именем «Claude Code (<как пользователь назвал сервер>)», а мы назвали сервер ai-budget — и он зарегистрировался как «Claude Code (ai-budget)», а наша защита от выдачи себя за нас его отвергла. Любой, кто назвал бы коннектор нашим именем, упёрся бы в непонятную ошибку. Мы исправили это в тот же день: метка в скобках в конце имени больше не проверяется, если перед ней что-то есть, а «AI Budget (official)» и просто «(AI Budget)» по-прежнему отвергаются. После этого весь путь заработал — обнаружение, регистрация, согласие, токен, подключение и список инструментов.

Один вопрос оставляем открытым: лимит регистрации считается по IP, и если платформа регистрирует клиентов со своих общих серверов, а не из браузера пользователя, все её пользователи делили бы одну корзину. Прежде чем заявлять коннектор в каталогах, мы записываем адреса регистрации настоящих клиентов и при необходимости поднимаем лимит для конкретной платформы.

Как подключить

В Claude откройте Настройки → Коннекторы, добавьте свой коннектор и введите https://api.ai-budget.pl/mcp. В тарифах Team и Enterprise свои коннекторы добавляет только владелец организации — мы сами на это наткнулись. Другие ассистенты с поддержкой удалённых MCP-коннекторов принимают тот же адрес.

Ассистент откроет страницу AI Budget, где вы войдёте как обычно. На ней будет имя ассистента с пометкой, что он зарегистрировался сам, и хост, куда уйдёт доступ. Отметьте счета, которые он может читать, и разрешите. Чтобы отключить его, откройте в AI Budget Настройки → Подключённые приложения и отключите его; доступ пропадёт на следующем же вызове.

Частые вопросы

Может ли ассистент изменить мои данные в AI Budget?
Нет. У коннектора только инструменты чтения: счета, расходы, доходы, категории, бюджеты и суммы трат. Он ничего не добавляет, не меняет и не удаляет и не скачивает фото чеков.
Нужен ли API-ключ?
Нет. Вы вводите в ассистенте адрес https://api.ai-budget.pl/mcp, ассистент регистрируется сам, а вы подтверждаете доступ на странице согласия AI Budget и выбираете счета.
Как отозвать доступ у ассистента?
В AI Budget откройте Настройки → Подключённые приложения и отключите ассистента. Права проверяются при каждом вызове, поэтому доступ пропадёт на следующем же запросе.
Работает ли это с зашифрованными счетами?
Счёт с полным сквозным шифрованием прочитать нельзя. На счёте с шифрованием текстов зашифрованные поля остаются скрытыми — так же, как для любого подключённого приложения.