Аутентификация MCP

MCP-сервер поддерживает несколько способов аутентификации для разных сценариев использования.

Token-based (рекомендуемый)

Токен кодирует в себе все необходимые параметры сессии: userId, agentId, todoListId.

GET /api/agent/mcp?token=YOUR_MCP_TOKEN

Где взять токен: В настройках агента в Timelix → вкладка Tools → секция MCP Access → кнопка Создать токен.

Как хранится: Таблица mcpAccessTokens в базе данных.

// Что возвращает валидация токена
{
  userId: string;
  agentId: string;
  todoListId: string;
  expiresAt?: Date;
}

Ошибки:

Legacy: прямые параметры

Обратно-совместимый формат — параметры передаются напрямую в URL. Используется в старых интеграциях.

GET /api/agent/mcp?userId=xxx&agentId=yyy&todoListId=zzz

Widget Token

Для встраивания агента в сторонние сайты через виджет. Токен передаётся в заголовке HTTP-запроса, а не в URL.

POST /api/agent/chat
X-Widget-Token: YOUR_WIDGET_TOKEN

Виджет-токен привязан к конкретному агенту — пользователь не может выбрать другого. Используется, когда агент встроен на сайт клиента.

// Что возвращает валидация виджет-токена
{
  userId: string;
  agentId: string;  // зафиксирован в токене
}

Server-to-Server (Proactive Trigger)

Для запуска агента по событиям с сервера (cron, webhooks, системные события).

POST /api/agent/chat
X-Proactive-Trigger: true
X-Internal-Secret: PROACTIVE_TRIGGER_SECRET

PROACTIVE_TRIGGER_SECRET — переменная окружения на стороне Timelix. Значение знают только серверные сервисы (N8N, cron-jobs).

Выбор способа аутентификации