К содержанию
TelegaFirst

Для AI-агентов: markdown этой страницы — /docs/connect-claude-code.mdиндекс документации — /llms.txt

Подключить Claude Code

Обновлено

Подключение даёт вашему агенту доступ к AI-фронт-офису в Telegram в пределах ваших прав. Нужны аккаунт выбранного клиента, Telegram для входа человека и доступный HTTPS endpoint. Инструкции сверены с официальными источниками 2026-09-30; успешный ручной проход этого хоста и его конкретная версия здесь не заявлены.

Настройка

Добавьте удалённый сервер через CLI:

claude mcp add --transport http telegafirst https://mcp.telegafirst.com/api/v1/mcp
claude mcp get telegafirst

В Claude Code откройте /mcp, выберите TelegaFirst и пройдите браузерную авторизацию. Сообщение о добавлении означает сохранение конфигурации; состояние Connected и успешный вызов проверяются отдельно. При конфигурации project scope Claude Code запрашивает доверие к .mcp.json. Команды здесь показаны для ручного выполнения, установка Claude Code не является частью входа TelegaFirst. Официальная документация Claude Code.

Discovery и согласие

Используйте canonical endpoint https://mcp.telegafirst.com/api/v1/mcp с Streamable HTTP. При первом неавторизованном запросе сервер возвращает HTTP 401 с WWW-Authenticate; клиент получает OAuth discovery и открывает вход. Подтвердите показанное согласие в Telegram от своего имени. Отказ завершает вход, а не создаёт обходной API key. Подробности и различия credentials — авторизация.

Инструменты и бизнес

После OAuth обновите tools/list. У нового владельца без бизнеса доступны три dedicated-инструмента: get_onboarding_state, check_slug_availability и claim_slug, а также пять scoped meta-tools: search_admin_tools, load_domain, describe_tool, execute_admin_read и execute_admin_write. До создания бизнеса их targets ограничены состоянием, проверкой адреса и claim своего бизнеса; документационные MCP-инструменты пока недоступны. Сначала прочитайте состояние и body.entry_context, согласуйте адрес и язык, затем выполните claim. Следуйте response.next_action и проверкам готовности, а после их изменения снова обновите список. До появления бота не требуйте identity или каталог. Полный порядок — новый бизнес.

Для существующего бизнеса проверьте доступные бизнесы, их role (owner или operator) и активный контекст. Если нужен другой, переключайте общий контекст человека только разрешённым инструментом и снова читайте tools/list; это меняет контекст и в других подключениях. API key без человека не переключает этот указатель. Порядок — существующий бизнес.

Каталог и результат

Когда readiness, scope catalog:read и тариф допускают чтение, вызовите get_catalog с {"limit":10,"zone":"ru"}. Результат — страницы вашего каталога с внешними номерами; пустой каталог тоже допустим. Не придумывайте позиции и не считайте схему инструмента успешным вызовом. Если dedicated tool не установлен, discovery через load_domain/describe_tool не добавляет его автоматически: используйте существующий meta-dispatch согласно MCP-руководству.

Подключение подтверждено для вашей сессии только после успешного вызова и проверки нужного бизнеса. Чтение каталога не разрешает денежные операции; для записи нужны отдельные права. Номера объектов принадлежат активному бизнесу и не используются в анонимных публичных ссылках.

Контрактный пример состояния

Сокращённая обезличенная проекция get_onboarding_state до первого бизнеса. Это пример серверного контракта, а не запись успешного входа из данного хоста. Текст response.next_action.say_to_user и подсказки hint опущены; реальный ответ используйте целиком.

{"tenant":{"slug":null,"bot_username":null},"active_slug":null,"stage":"address","status":"todo","next_action":{"goal":"address","collect":[{"field":"slug"},{"field":"language"}]},"body":{"entry_context":{"intent":"auto","active_business":null,"owned_businesses":[],"recommended_business_slug":null,"action":"create_business"},"completedSteps":[],"site_operation":null,"language":"ru"}}

После claim_slug следующий шаг определяется новым ответом; опубликованный сайт сам по себе не означает готовый бот. При попытке сменить уже выданный адрес сервер возвращает SLUG_IMMUTABLE; сохраните исходный адрес и продолжайте readiness.

Если подключение не удалось

При HTTP 401 пройдите вход заново; при отказе прав проверьте consent, live роль и выбранный бизнес. При PLAN_UPGRADE_REQUIRED проверьте тариф и открытое оплаченное окно. Если инструмента нет, обновите список и readiness; не подменяйте вход токеном другого приложения. Сбой установки на неподдерживающем клиенте не исправляется одним промптом. Коды ошибок, права и scopes, curl-диагностика.

Продолжение настройки с агентом

Полное описание платформы: https://mcp.telegafirst.com/llms-full.txt. После подключения прочитайте нужный навык через MCP и подтвердите актуальный пакет через ack_skills, когда этого требует сервер.

Первое действие агента — get_onboarding_state с intent: auto. Проверьте выбранный бизнес и используйте текущий response.next_action: расскажите человеку next_action.say_to_user, запросите только отсутствующие поля из next_action.collect, выполните разрешённый next_action.execution.tool с известными next_action.execution.arguments. Учитывайте next_action.execution.executor: агент выполняет только действия для agent, для owner показывает точную инструкцию человеку, для server ждёт по выданным условиям. Продолжайте через next_action.execution.continue_with, если оно задано. Если не хватает прав, покажите предусмотренное восстановление доступа. После действия проверьте результат и снова прочитайте состояние; ожидание и повтор выполняются по серверной инструкции. Этот текст не задаёт отдельный порядок шагов.

Токен собственного Telegram-бота можно передать агенту для авторизованного register_existing_bot через поле params.arguments.bot_token его MCP-запроса. Если сервер предлагает продолжить уже начатое подключение, используйте resume_bot_connection с пустыми аргументами. Приём токена не доказывает подключение: connected: true появляется только после завершения серверного процесса. Учётные данные платёжного провайдера также передаются через предусмотренный типизированный инструмент выбранного бизнеса. Агент не повторяет секреты в ответах и не сохраняет их в документах, URL или отчётах. Авторизация самого MCP-коннектора остаётся в настройках приложения.

Для тестового товара нужны полная карточка и отдельное полное сообщение доставки. Поддерживаются текст, фото, видео, PDF, другие допустимые документы, несколько файлов и допустимые альбомы; фото необязательно. Возможность прочитать вложение, получить HTTPS-ссылку или отправить точные байты проверяется в вашем приложении. Импорт через media_import_files, загрузка через media_request_upload → HTTP PUT → media_finalize, проверка media_get_status и переход к вебу/Mini App описаны в руководстве по файлам. В контент передаются только подтверждённые постоянные mediaRefs. Агент не придумывает ссылку и не обещает доставку без проверки.

Для первой живой оплаты сервер может предложить onboarding_prepare_first_payment и onboarding_execute_first_payment; нужны одновременно catalog:write AND payments:config. Агент показывает подготовленные условия и получает явное подтверждение владельца перед исполнением. Подтверждение цены активирует существующий товар для покупки; публичная видимость настраивается отдельно. Для нативных Stars/CryptoBot зона покупки .ru или .com выбирается явно, а не по языку; для PayPal явно выбирается окружение. Минимальную сумму определяет провайдер. Подтверждение владельцем настроек callback и подписи не доказывает доставку настоящего callback, проверку его подписи или живую оплату. Отправленная карточка товара также не означает оплату или начисленный бонус: эти факты проверяются сервером.

После короткого отвлекающего вопроса агент возвращается к текущему шагу. По просьбе остановиться он прекращает работу. Для завершения сохраните ответы об устройстве, приложении ИИ и платной или бесплатной подписке, затем выполните доступное отдельное действие onboarding_complete. Только подтверждённое сервером journey.completed завершает настройку и выключает её сопровождение. Открытие ссылки, копирование промпта и закрытие окна завершением не считаются.