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

Работа с MCP

Обновлено 2 октября 2026 г.

Подключите своего AI-агента к TelegaFirst, чтобы настроить AI-фронт-офис и работать с бизнесом в пределах выданных прав. Владелец и операторы продолжают работать с диалогами в Telegram. Для подключения нужны клиент с поддержкой удалённого MCP и OAuth, Telegram для подтверждения человеком и доступный HTTPS endpoint.

#Адрес и подключение

Канонический endpoint — https://mcp.telegafirst.com/api/v1/mcp, транспорт — Streamable HTTP. Этот адрес одинаков для документации на .ru и .com. Подключение по URL не требует запуска локального stdio-сервера. Для согласованного локального стенда используйте объявленный им HTTPS endpoint: ресурс MCP и OAuth discovery должны относиться к одному стенду.

Выберите инструкцию: ChatGPT, Claude web/Desktop, Claude Code, Codex, Cursor, Antigravity, Gemini Spark: границы поддержки. Возможность добавить удалённый сервер зависит от конкретного клиента; промпт не устанавливает отсутствующий коннектор.

1. Добавьте endpoint способом, который поддерживает ваш клиент.

2. Пройдите предложенную OAuth-авторизацию от своего имени и прочитайте согласие перед подтверждением в Telegram.

3. Обновите tools/list и прочитайте get_onboarding_state. Для нового бизнеса сначала выберите адрес; для существующего проверьте активный бизнес и готовность.

4. Выполняйте только доступные операции, учитывая их schema, scopes, risk и текущие ограничения. Проверяйте результат каждого изменения.

OAuth-подключение человека использует реальный OAuthGrant; ключ интеграции относится к ExternalApp, а headless credential — к M2MCredential. Сессия покупателя, полученная через create_session, не даёт агенту право управлять бизнесом. Различия субъектов и отзыв доступа.

#HTTP 401 начинает вход

Без credential сервер отвечает HTTP 401 с WWW-Authenticate, в том числе на initialize и tools/list. Клиент читает resource_metadata, получает discovery и запускает OAuth. Это транспортный challenge: чтение публичной документации не делает MCP анонимным. Такой механизм описан в официальной спецификации авторизации MCP.

Контрактный пример запроса без credential:

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Заголовок для канонического endpoint; перечислены все девять consent bundles в порядке публикации:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.telegafirst.com/.well-known/oauth-protected-resource/api/v1/mcp", scope="workspace-read customer-conversations-read bot-setup conversations storefront-and-marketing ai-and-knowledge access-and-integrations platform-support money-operations"

Тело challenge для запроса с id: 1:

{"jsonrpc":"2.0","error":{"code":-32001,"message":"Authentication required. Approve the connection in Telegram to continue.","data":{"code":"UNAUTHORIZED"}},"id":1}

Эти примеры описывают серверный контракт; они не являются записью ручного подключения через конкретный AI-клиент. При повторном 401 после входа проверьте endpoint и credential, затем повторите авторизацию. Не извлекайте токен из другого AI-клиента и не подменяйте его ключом с более широкими правами. Для независимой диагностики есть собственный device-grant клиент на curl.

#Что означает список инструментов

tools/list сообщает инструменты, рекламируемые этому подключению сейчас. Общий справочник описывает определения; он не обещает, что весь справочник одновременно установлен в вашем клиенте. На состав влияют субъект, scopes, тариф, активный бизнес, наличие бота и readiness.

До первого бизнеса доступны три dedicated-инструмента состояния, проверки адреса и claim своего бизнеса, а также пять scoped meta-tools. До создания бизнеса их discovery и proxy-вызовы ограничены состоянием, проверкой адреса и claim своего бизнеса; после claim доступны разрешённые onboarding/site-targets. Ни identity-инструменты, ни документационные MCP-инструменты, ни каталог ещё не доступны:

{"tools":["check_slug_availability","claim_slug","describe_tool","execute_admin_read","execute_admin_write","get_onboarding_state","load_domain","search_admin_tools"]}

Это обезличенная проекция имён из результата tools/list, а не полный JSON-RPC envelope или список descriptor objects. Пример вызова первого шага:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_onboarding_state","arguments":{}}}

Успех означает, что получены текущие stage, status и next_action; затем выполните предложенный шаг. Появление сайта ещё не означает наличие бота или готовность каталога. После claim и после изменения readiness снова прочитайте tools/list.

Для человека с существующим бизнесом проверьте активный slug перед изменением. switch_active_bot, когда он доступен и разрешён, меняет общий активный бизнес человека; другие его подключения используют тот же выбор. Закэшированный клиентом список может устареть: сервер сообщает cache_hints.tools_list_ttl_seconds: 60. После переключения обновите список и состояние. При ACTIVE_BOT_CHANGED перечитайте контекст и согласуйте цель, затем сформируйте новый запрос.

#Progressive disclosure: schema и callable tool

Когда нужного инструмента нет в установленном списке, используйте доступные meta-tools:

load_domain и describe_tool возвращают schema внутри результата. Они не устанавливают callable tool в клиенте и не меняют tools/list уведомлением list_changed. Обнаруженная schema также не добавляет отсутствующий scope.

Proxy повторно проверяет права целевого инструмента и проходит тот же путь исполнения: scope, plan, активный бот, resource limiter, validation и handler. Read proxy не выполняет write; write proxy не выполняет read. Для risk destructive, money или неизвестного risk нужен отдельный typed tool: такие targets через proxy отклоняются. Не запускайте их повторно под другим именем ради обхода отказа.

#Успех и отказ

Успешный tools/call возвращает content; structuredContent присутствует у инструментов с объявленной outputSchema. После допуска к tool layer ошибка известного инструмента возвращается как isError: true с безопасным сообщением. Не считайте успешный HTTP ответ доказательством успешного изменения: проверьте MCP result.

Проверка scope прямого tool call может завершиться до tool layer: HTTP 403, INSUFFICIENT_SCOPE и WWW-Authenticate: Bearer error="insufficient_scope". Required scope может отсутствовать в эффективном наборе из-за согласия, текущих прав или тарифного ограничения. Код и текст challenge сами по себе не доказывают конкретную причину. Сверьте выданные и эффективные scopes, активный бизнес, permissions, план и платное окно. Проверка plan при исполнении target через meta-tool может вернуть PLAN_UPGRADE_REQUIRED; прямой вызов при том же ограничении может уже завершиться с INSUFFICIENT_SCOPE. Повторное согласие, новый ключ или смена credential не открывают закрытое платное окно.

Неизвестный params.name или отсутствующее имя — ошибка протокола. Неожиданная внутренняя ошибка скрывает детали и сообщает traceId для обращения в поддержку. Транспортный 401 нужно обрабатывать на уровне подключения, до повторного tool call.

Объекты бизнеса адресуются tenant-scoped номерами из ответа, а ссылки для публикации используют opaque code. Идентификаторы и пагинация. Точные параметры операций приведены в MCP-справочнике; для списка и detail заказов используйте объявленные REST операции, не выдумывайте list_orders или get_order как MCP-инструменты.