--- title: "TukTuk для нейросетей: MCP-сервер и API для ИИ-агентов" nav_title: "Для нейросетей и MCP" url: https://docs.tuk-tuk.online/api/agents markdown: https://docs.tuk-tuk.online/api/agents.md section: "API для разработчиков" description: "Как подключить tuk-tuk.online к нейросети: MCP-сервер @tuktuk/mcp одной строкой, ключ API со scopes, манифест возможностей, отправка и отложенные сообщения, рассылки, автоматизация и подписка на входящие события. Токены Telegram и других площадок искать не нужно." keywords: ["MCP сервер", "Model Context Protocol", "API для ИИ-агента", "нейросеть отправка сообщений", "Claude MCP Telegram", "агент мессенджер API", "llms.txt", "openapi", "отложенная отправка API", "AI агент рассылка"] lang: ru product: tuk-tuk.online app: https://lk.tuk-tuk.online api_base: https://back.tuk-tuk.online --- > [!AI] Кратко > Как подключить tuk-tuk.online к нейросети: MCP-сервер @tuktuk/mcp ставится одной строкой, ключ API со scopes выпускается в кабинете, манифест GET /api/v1/manifest отвечает, что доступно этому ключу. Платформа хранит подключения к мессенджерам, доставляет сообщения, выполняет отложенные действия и присылает входящие вебхуком. > > - MCP: `npx -y https://docs.tuk-tuk.online/mcp/tuktuk-mcp.tgz`, переменные `TUKTUK_API_KEY` (обязательно) и `TUKTUK_API_URL` (по умолчанию `https://back.tuk-tuk.online/api/v1`). > - Инструменты MCP показываются по правам ключа; без ключа доступен один инструмент с инструкцией, как ключ получить. > - Первый вызов агента: `GET /api/v1/manifest`, он возвращает список ресурсов, требуемые права и признак доступности для текущего ключа. > - Полная спецификация: `GET /api/v1/openapi.json` в формате OpenAPI 3.1. > - Отложенная отправка: `POST /api/v1/messages/schedule` с полем `sendAt` в ISO-8601, минимум на 30 секунд в будущем; отмена `DELETE /api/v1/messages/scheduled/{id}`. > - Повтор запроса безопасен с заголовком `Idempotency-Key`: вернётся первый результат, дубль клиенту не уйдёт. > - Перед массовой отправкой: `POST /api/v1/broadcasts/preview` считает аудиторию, `GET /api/v1/account` показывает, разрешена ли отправка. > - Чтобы ИИ-ассистент аккаунта не отвечал параллельно с внешним агентом: `POST /api/v1/assistants/pause-dialog` с `dialogId` и `minutes`. > - Токены Telegram, VK и других площадок агенту не нужны: подключения хранит платформа, единственный секрет, это ключ `tuk_sk_...`. > - Через API нельзя выпускать ключи, платить, менять тариф и управлять правами пользователей. > > Связанные страницы: https://docs.tuk-tuk.online/api, https://docs.tuk-tuk.online/api/rest, https://docs.tuk-tuk.online/api/webhooks, https://docs.tuk-tuk.online/broadcasts, https://docs.tuk-tuk.online/chains, https://docs.tuk-tuk.online/channels # TukTuk для нейросетей Нейросеть умеет думать, писать текст и принимать решения. Она не умеет держать соединение с Telegram неделями, пережить собственный перезапуск, дождаться завтрашнего утра и гарантировать доставку сообщения. TukTuk берёт это на себя. Агенту остаётся один секрет, ключ TukTuk, вместо своего сервера, токенов площадок и очереди задач. ## Что мы держим вместо агента | Что даём | Почему агент не может сам | |---|---| | Подключения к площадкам | Токены ботов, сессии, OAuth, SMTP и IMAP живут у нас и переживают любой перезапуск агента | | Доставку | Лимиты площадок, повторные попытки, статусы отправки, списание баланса | | Время | Отправка в конкретный момент, рассылки по окну, зациклённые воронки автопостинга | | Память о клиенте | История переписки, теги, произвольные поля, вложения, расшифровки голосовых | | Обратный канал | Входящие приходят вебхуком на ваш адрес, поллинг не нужен | ## Быстрый старт за четыре шага 1. Зарегистрируйтесь: [https://lk.tuk-tuk.online/register](https://lk.tuk-tuk.online/register). Есть бесплатный тариф. 2. Подключите канал в разделе «Каналы связи»: Telegram-бот, чат-виджет, Email, SMS-шлюз. 3. Выпустите ключ: Настройки проекта, вкладка **API**, «Создать ключ». Формат `tuk_sk_...`, показывается один раз. 4. Проверьте доступ: ```bash curl https://back.tuk-tuk.online/api/v1/me -H "Authorization: Bearer $TUKTUK_API_KEY" ``` > [!TIP] > Токен Telegram и ключи других площадок агенту искать не нужно: они хранятся внутри платформы. Единственный секрет у агента, это ключ TukTuk. ## MCP-сервер Для клиентов с поддержкой Model Context Protocol (Claude Code, Claude Desktop, Cursor и другие) есть готовый сервер. ```bash claude mcp add tuktuk --env TUKTUK_API_KEY=tuk_sk_... -- npx -y https://docs.tuk-tuk.online/mcp/tuktuk-mcp.tgz ``` Или в конфигурации клиента: ```json { "mcpServers": { "tuktuk": { "command": "npx", "args": ["-y", "https://docs.tuk-tuk.online/mcp/tuktuk-mcp.tgz"], "env": { "TUKTUK_API_KEY": "tuk_sk_..." } } } } ``` | Переменная | Обязательна | Значение | |---|---|---| | `TUKTUK_API_KEY` | да | Ключ рабочего пространства | | `TUKTUK_API_URL` | нет | По умолчанию `https://back.tuk-tuk.online/api/v1` | Инструменты показываются по правам ключа: read-only ключ не увидит отправку. Без ключа сервер стартует и показывает один инструмент с инструкцией, как ключ получить. Все инструменты с параметрами: [Инструменты MCP](https://docs.tuk-tuk.online/api/mcp-tools). Что лежит в тарболе и какой он версии, показывает [version.json](https://docs.tuk-tuk.online/mcp/version.json). > [!NOTE] > Пакет ставится тарболом с нашего сайта, а не из реестра npm: в npm он пока не опубликован. Строка подключения от этого не меняется: `npx` одинаково умеет и то, и другое. ## Манифест возможностей Первый вызов, который стоит сделать агенту. Он отвечает, что доступно именно этому ключу, и избавляет от угадывания. ```bash curl https://back.tuk-tuk.online/api/v1/manifest -H "Authorization: Bearer $TUKTUK_API_KEY" ``` В ответе: список ресурсов, каждый эндпоинт с нужным правом и признаком `available`, соглашения по формату ответа и ошибкам, ссылки на документацию, команда установки MCP и перечень того, чего в API нет намеренно. Полная спецификация: `GET https://back.tuk-tuk.online/api/v1/openapi.json` в формате OpenAPI 3.1. ## Что агент может делать | Задача | Вызов | |---|---| | Узнать подключённые каналы | `GET /messengers` | | Найти клиента | `GET /contacts?phone=%2B79991234567` | | Прочитать переписку | `GET /contacts/{id}/messages?limit=20` | | Написать сейчас | `POST /messages` | | Написать завтра в 9 утра | `POST /messages/schedule` | | Положить файл в постоянное хранилище | `POST /files` | | Посчитать аудиторию рассылки | `POST /broadcasts/preview` | | Запустить рассылку | `POST /broadcasts`, затем `POST /broadcasts/{id}/start` | | Собрать автоответ | `POST /chains` | | Забрать диалог у ИИ-ассистента | `POST /assistants/pause-dialog` | | Получать входящие на свой адрес | `POST /events/subscriptions` | Все эндпоинты с примерами: [REST API v1](https://docs.tuk-tuk.online/api/rest). ## Отложенное действие Главный сценарий для агента: поставить сообщение и завершиться. Момент отправки держит платформа. ```bash curl -X POST https://back.tuk-tuk.online/api/v1/messages/schedule \ -H "Authorization: Bearer $TUKTUK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"dialogId":"f1e2...","text":"Напоминаю о встрече","sendAt":"2026-09-10T06:00:00Z"}' ``` Время указывается в ISO-8601, минимум на 30 секунд вперёд. Список отложенных: `GET /messages/scheduled`. Отмена до отправки: `DELETE /messages/scheduled/{id}`. ## Правила, которые берегут деньги пользователя - Перед массовой отправкой считайте аудиторию через `POST /broadcasts/preview`. Отправка платная, ошибка в фильтре стоит денег. - Проверяйте `GET /account`: при `canSend: false` отправка не пройдёт, там же указана причина. - Если в аккаунте работает ИИ-ассистент, а переписку ведёте вы, заберите диалог: `POST /assistants/pause-dialog` с `{"dialogId":"...","minutes":60}`. Иначе клиент получит два ответа. - При повторе запроса передавайте заголовок `Idempotency-Key`: повтор вернёт первый результат вместо второго сообщения. ## Справочники | Что нужно | Где | |---|---| | Все эндпоинты с правами | [Справочник эндпоинтов](https://docs.tuk-tuk.online/api/reference) | | Все инструменты MCP с параметрами | [Инструменты MCP](https://docs.tuk-tuk.online/api/mcp-tools) | | Законченные сценарии: ответить, написать первым, рассылка, события | [Сценарии для агента](https://docs.tuk-tuk.online/api/recipes) | | Тела запросов и примеры кода | [REST API v1](https://docs.tuk-tuk.online/api/rest) | ## Машиночитаемая документация | Файл | Что внутри | |---|---| | [tuk-tuk.online/llms.txt](https://tuk-tuk.online/llms.txt) | Карта сервиса: что умеем, как начать, где ключ | | [https://docs.tuk-tuk.online/llms.txt](https://docs.tuk-tuk.online/llms.txt) | Оглавление документации | | [https://docs.tuk-tuk.online/llms-full.txt](https://docs.tuk-tuk.online/llms-full.txt) | Вся документация одним файлом | | [tuk-tuk.online/mcp.json](https://tuk-tuk.online/mcp.json) | Манифест MCP-сервера | | `https://back.tuk-tuk.online/api/v1/openapi.json` | Спецификация API | Любая страница документации доступна как Markdown: тот же адрес плюс `.md`. Например, [https://docs.tuk-tuk.online/api/rest.md](https://docs.tuk-tuk.online/api/rest.md). ## Границы Через API нельзя выпускать и отзывать ключи, платить, менять тариф и управлять правами пользователей. Эти действия остаются за владельцем рабочего пространства в кабинете. Ключ видит только своё рабочее пространство: чужой идентификатор возвращает `404`. Модель прав, срок действия ключа, белый список IP и лимит запросов: [REST API v1](https://docs.tuk-tuk.online/api/rest).