# Работа с MCP Source: Locale: ru releaseGitSha: c9a428d902de0b479a981e43774f38b9ec077ed7 sourceContentDigest: bd1180a4870f27f4e361d997af4b925e4668fe36a471b606c885ea6b43854372 Version: 1 Подключите своего 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](https://telegafirst.com/docs/connect-chatgpt), [Claude web/Desktop](https://telegafirst.com/docs/connect-claude-ai), [Claude Code](https://telegafirst.com/docs/connect-claude-code), [Codex](https://telegafirst.com/docs/connect-codex), [Cursor](https://telegafirst.com/docs/connect-cursor), [Antigravity](https://telegafirst.com/docs/connect-antigravity), [Gemini Spark: границы поддержки](https://telegafirst.com/docs/connect-gemini-spark). Возможность добавить удалённый сервер зависит от конкретного клиента; промпт не устанавливает отсутствующий коннектор. 1. Добавьте endpoint способом, который поддерживает ваш клиент. 2. Пройдите предложенную OAuth-авторизацию от своего имени и прочитайте согласие перед подтверждением в Telegram. 3. Обновите `tools/list` и прочитайте `get_onboarding_state`. Для [нового бизнеса](https://telegafirst.com/docs/getting-started#new-business) сначала выберите адрес; для [существующего](https://telegafirst.com/docs/getting-started#existing-business) проверьте активный бизнес и готовность. 4. Выполняйте только доступные операции, учитывая их schema, scopes, risk и текущие ограничения. Проверяйте результат каждого изменения. OAuth-подключение человека использует реальный `OAuthGrant`; ключ интеграции относится к `ExternalApp`, а headless credential — к `M2MCredential`. Сессия покупателя, полученная через `create_session`, не даёт агенту право управлять бизнесом. [Различия субъектов и отзыв доступа](https://telegafirst.com/docs/authorization). ## HTTP 401 начинает вход Без credential сервер отвечает HTTP `401` с `WWW-Authenticate`, в том числе на `initialize` и `tools/list`. Клиент читает `resource_metadata`, получает discovery и запускает OAuth. Это транспортный challenge: чтение публичной документации не делает MCP анонимным. Такой механизм описан в [официальной спецификации авторизации MCP](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/docs/specification/2026-07-28/basic/authorization/index.mdx). Контрактный пример запроса без credential: ```json {"jsonrpc":"2.0","id":1,"method":"tools/list"} ``` Заголовок для канонического endpoint; перечислены все девять consent bundles в порядке публикации: ```http 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`: ```json {"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](https://telegafirst.com/docs/curl-device-grant). ## Что означает список инструментов `tools/list` сообщает инструменты, рекламируемые этому подключению сейчас. Общий справочник описывает определения; он не обещает, что весь справочник одновременно установлен в вашем клиенте. На состав влияют субъект, scopes, тариф, активный бизнес, наличие бота и readiness. До первого бизнеса доступны три dedicated-инструмента состояния, проверки адреса и claim своего бизнеса, а также пять scoped meta-tools. До создания бизнеса их discovery и proxy-вызовы ограничены состоянием, проверкой адреса и claim своего бизнеса; после claim доступны разрешённые onboarding/site-targets. Ни identity-инструменты, ни документационные MCP-инструменты, ни каталог ещё не доступны: ```json {"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. Пример вызова первого шага: ```json {"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: | Инструмент | Результат | Следующий шаг | | --------------------- | ---------------------------------------------------------------- | -------------------------------------- | | `search_admin_tools` | Имена подходящих инструментов; подробность задаёт `detail_level` | Выберите `tool_id` и прочитайте schema | | `load_domain` | Descriptors одного домена внутри результата | Проверьте scopes, risk и параметры | | `describe_tool` | Полный descriptor выбранного `tool_id` | Подготовьте точные параметры | | `execute_admin_read` | Вызов доступного target с risk `read` | Прочитайте результат | | `execute_admin_write` | Вызов доступного target с risk `write` | Проверьте результат изменения | `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. | Ситуация | Действие | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTTP 401 / отозванный credential | Повторите вход: [авторизация](https://telegafirst.com/docs/authorization), [INVALID\_API\_KEY](https://telegafirst.com/docs/errors#INVALID_API_KEY), [INVALID\_JWT](https://telegafirst.com/docs/errors#INVALID_JWT) | | `INSUFFICIENT_SCOPE` | Сверьте выданные и эффективные scopes, текущие права, план и платное окно: [права](https://telegafirst.com/docs/scopes-and-permissions), [ошибка](https://telegafirst.com/docs/errors#INSUFFICIENT_SCOPE) | | `PLAN_UPGRADE_REQUIRED` | Проверьте план и открытое платное окно: [права и тариф](https://telegafirst.com/docs/scopes-and-permissions#paid-window) | | `FORBIDDEN` при proxy | Проверьте risk и разрешённый target; [FORBIDDEN](https://telegafirst.com/docs/errors#FORBIDDEN) | | Бизнес или бот ещё не готов | Продолжите `next_action` из [начала работы](https://telegafirst.com/docs/getting-started) | | Conflict, устаревший ETag или повтор изменения | Следуйте [ETag и идемпотентности](https://telegafirst.com/docs/etag-and-idempotency); не выполняйте денежное действие вслепую повторно | Объекты бизнеса адресуются tenant-scoped номерами из ответа, а ссылки для публикации используют opaque code. [Идентификаторы и пагинация](https://telegafirst.com/docs/identifiers-and-pagination). Точные параметры операций приведены в MCP-справочнике; для списка и detail заказов используйте объявленные REST операции, не выдумывайте `list_orders` или `get_order` как MCP-инструменты.