MCP-сервер

MCP (Model Context Protocol) даёт AI-клиенту доступ к диалогам Amobit Chats: поиск, историю сообщений и — при явном разрешении — отправку ответа. Токен ограничен компанией, выбранными каналами и сроком действия.

Транспорт: Streamable HTTP (stateless JSON)Токен: acmcp_…Эндпоинты: /api/v1/mcp/reference/ и /api/v1/mcp/tools/

Пользовательская инструкция — на странице /mcp. Там настройка Codex, Claude Code и Cursor, сценарии и частые вопросы. Эта страница — контракт для разработчика: эндпоинты, инструменты, лимиты и правила доступа.

Эндпоинты

Адрес	Доступ	Назначение
`POST /api/v1/mcp/reference/`	Без токена	Публичная справка: единственный инструмент `amobit_get_api_help`. Удобно, чтобы AI-клиент узнал схему до выпуска токена.
`POST /api/v1/mcp/tools/`	`Authorization: Bearer acmcp_…`	Рабочие инструменты: каналы, диалоги, сообщения, отправка (если включена).
`GET /mcp`	Публично	Инструкция по подключению, примеры конфигурации.
`GET /mcp/access`	Публичная страница; управление — сессия owner/admin	Выпуск и отзыв токенов, выбор каналов, журнал последних обращений.
`POST /api/v1/mcp/workspaces/{workspace_slug}/credentials/`	Сессия + CSRF	Выпуск токена из кабинета. `POST …/credentials/{id}/revoke/` — отзыв.

Протокол

Поддерживаются initialize, уведомления, ping, tools/list и tools/call для версий 2025-03-26, 2025-06-18 и 2025-11-25.
Только POST. GET и DELETE отвечают 405: серверных сессий и SSE-потока нет.
Клиент передаёт Accept: application/json, text/event-stream и Content-Type: application/json.
Заголовок Origin проверяется; тело запроса ограничено 32 КиБ.
Batch-запросы и неизвестные аргументы инструментов не принимаются — это защита от неявного расширения контракта.
OAuth discovery и устаревший HTTP+SSE не предоставляются.

Токены

Свойство	Значение
Формат	`acmcp_` + случайная строка.
Выпуск	`/mcp/access` или API кабинета; нужна роль owner/admin и привязка компании к Amobit ID.
Срок	1–90 дней, задаётся при выпуске.
Каналы	Явный список каналов одной компании; новые каналы к токену не добавляются.
Права	По умолчанию только чтение. Отправка включается флагом `can_send` при выпуске.
Лимит	До 20 одновременно действующих токенов на компанию.
Хранение	SHA-256-хеш; полный токен показывается один раз и в браузерные хранилища не записывается.
Проверка	На каждом запросе: срок, отзыв, активность компании, организация и актуальная роль создателя. Снятие администратора закрывает доступ сразу.
Аудит	Записывается `started`, затем `success` или `error`: инструмент, время, компания, ID токена. Аргументы и тексты не пишутся.

Инструменты

Инструмент	Что делает	Параметры
`amobit_get_api_help`	Справка: обзор, инструменты, авторизация, сообщения, вебхуки.	`topic`: `overview` · `tools` · `auth` · `messages` · `webhooks`
`amobit_list_channels`	Разрешённые каналы и сохранённые статусы, без запроса к провайдеру.	`limit`, `offset`
`amobit_list_threads`	Поиск диалогов по имени/телефону, каналу, статусу и времени.	`query` ≤ 200, `channel_profile_id`, `status`, `since`, `limit`, `offset`
`amobit_search_messages`	Поиск текста сообщений, новые первыми.	`query` (2–200, обязателен), `channel_profile_id`, `since`, `direction`, `limit`, `offset`
`amobit_get_messages`	История одного диалога, новые первыми. Прочитанным не отмечает.	`thread_id` (обязателен), `since`, `limit`, `offset`
`amobit_send_message`	Текст в существующий диалог. Доступен только токену с `can_send`.	`thread_id`, `text` 1–4000, `idempotency_key` 8–128, `confirmed: true`

Статусы диалога для amobit_list_threads

open, waiting_operator, waiting_customer, bot, closed.

Ограничения ответов

По умолчанию 20 записей, максимум 50; offset не больше 10000. Ответ содержит items, has_more и next_offset.
Текст сообщения в истории обрезается до 8000 символов; при обрезании выставляется text_truncated.
Даты — ISO 8601 с часовым поясом.
Внутренние заметки, удалённые сообщения и raw payload не выдаются. Группы, отключённые в настройках канала, исключены.
Сохранённые статусы каналов возвращаются как есть (status_source: "saved_in_chats") и не означают проверку у провайдера.

Отправка через MCP

amobit_send_message использует тот же путь отправки, что и кабинет: тариф, доступность канала, окно Meta и защита от повторов сохраняются. Результат возвращается как:

Поле	Смысл
`message_id`	ID созданного сообщения.
`status`	Статус доставки на момент ответа.
`http_status`	HTTP-код внутреннего пути отправки.
`delivery_confirmed`	Всегда `false`: сервер не подтверждает факт доставки человеку.

confirmed: true — заявление AI-клиента, а не проверка сервером. Сервер требует его как признак того, что клиент показал человеку адресата и текст и получил подтверждение. Технический запрет отправки — токен только на чтение. Внешний AI-клиент должен включить approvals.

Ошибка провайдера не доказывает отсутствие отправки. При сетевой ошибке повторяйте тот же idempotency_key и сверяйте историю диалога: 202/502 не являются подтверждением доставки.

Лимиты частоты

Публичная справка /reference/ — 60 запросов в минуту на IP: для анонимного запроса действуют оба лимита, и более строгий — 60 в минуту.
Рабочий эндпоинт /tools/ — 120 запросов в минуту на IP и 60 в минуту на токен.
Лимиты считаются в процессе воркера (стандартный кэш Django), поэтому при нескольких воркерах суммарный предел выше; для строгой распределённой квоты нужен общий кэш.
Ответ 429 содержит заголовок Retry-After.

Примеры

Конфигурация клиента

URL:        https://chats.amobit.io/api/v1/mcp/tools/
Заголовок:  Authorization: Bearer acmcp_ВАШ_ТОКЕН
Транспорт:  Streamable HTTP, POST, JSON-RPC 2.0

# Готовые конфигурации для Codex, Claude Code и Cursor —
# на странице https://chats.amobit.io/mcp

Проверка без токена

curl -X POST https://chats.amobit.io/api/v1/mcp/reference/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Вызов инструмента

curl -X POST https://chats.amobit.io/api/v1/mcp/tools/ \
  -H "Authorization: Bearer acmcp_ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "amobit_list_threads",
      "arguments": {"limit": 10, "status": "open"}
    }
  }'

Ответы — JSON-RPC 2.0. Ошибка авторизации возвращается HTTP 401 с WWW-Authenticate: Bearer realm="Amobit Chats MCP"; ошибка аргументов — JSON-RPC error с описанием.

Хотите подключить AI-клиент за 5 минут? Откройте инструкцию по MCP и выпустите токен на /mcp/access.