Виртуальные ключи Альбато MCP

Виртуальный ключ — способ выпускать отдельные, узко ограниченные учётные данные для каждого агента или интеграции в Альбато MCP, вместо того чтобы использовать один общий токен Альбато. Общий обзор продукта смотрите в статье Что такое Альбато MCP, базовое подключение — в статье Быстрый старт.

Что такое виртуальный ключ

Виртуальный ключ (mcp_vk_...) — короткий токен, который вы используете вместо своего настоящего токена Альбато при настройке MCP-клиента.

Почему это важно: ваш настоящий токен Альбато может быть долгоживущим и использоваться не только здесь. Виртуальный ключ позволяет выпустить отдельный, узко ограниченный ключ для каждого агента или интеграции, если конфигурация одного MCP-клиента утечёт (например, случайно попадёт в репозиторий или скомпрометирован ноутбук), вы отзываете только этот виртуальный ключ одним запросом, не трогая ни настоящий токен Альбато, ни доступ других агентов.

Что нужно для начала

Вам понадобится секретный ключ регистрации (reg_...) — его выдаёт менеджер Альбато. Один такой ключ выдаётся на каждую компанию. Храните его надёжно: он позволяет создавать новые виртуальные ключи от имени вашего контракта.

Зарегистрировать виртуальный ключ

curl -X POST <MCP_SERVER_URL>/auth/register \
  -H "Authorization: Bearer <your_registration_secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "albatoToken": "<your_albato_token>",
    "label": "my-agent",
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Ответ:

{
  "virtualKey": "mcp_vk_a8f3bc9d...",
  "contractId": "acme",
  "albatoUserId": 136027,
  "albatoEmail": "user@example.com",
  "albatoName": "Jane Doe",
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "createdAt": "2026-07-09T10:00:00.000Z"
}

Поля albatoUserId, albatoEmail и albatoName определяют аккаунт Альбато, стоящий за только что переданным токеном — они заполняются автоматически, без дополнительных действий с вашей стороны. Если сервис аккаунтов Альбато на момент регистрации кратковременно недоступен, эти поля возвращаются пустыми (null), а ключ всё равно создаётся нормально — они заполнятся при следующем обновлении этого ключа.

Использовать виртуальный ключ в MCP-клиенте

Конфигурация Claude Desktop / MCP-клиента

{
  "mcpServers": {
    "albato": {
      "url": "<MCP_SERVER_URL>/mcp",
      "headers": {
        "Authorization": "Bearer mcp_vk_a8f3bc9d..."
      }
    }
  }
}

Прямой вызов API

curl <MCP_SERVER_URL>/mcp/tools \
  -H "Authorization: Bearer mcp_vk_a8f3bc9d..."

Полная последовательность подключения — в статье Быстрый старт.

Управлять ключами

Получить список всех ключей

curl <MCP_SERVER_URL>/client/keys \
  -H "Authorization: Bearer <your_registration_secret>"

{
  "contractId": "acme",
  "keys": [
    {
      "keyHint": "...9d3f",
      "label": "sales-agent",
      "albatoUserId": 136027,
      "albatoEmail": "user@example.com",
      "albatoName": "Jane Doe",
      "expiresAt": "2026-12-31T23:59:59.000Z",
      "createdAt": "2026-07-09T10:00:00.000Z"
    }
  ],
  "total": 1
}

keyHint — последние 4 символа виртуального ключа, нужны только для идентификации.

Поля albatoUserId, albatoEmail и albatoName особенно полезны, если ваш контракт выпускает один виртуальный ключ на каждого конечного пользователя — при сотнях или тысячах ключей так вы находите, какой ключ принадлежит какому пользователю, не поддерживая это соответствие самостоятельно. null означает, что ключ был зарегистрирован до того, как эта идентификация появилась, либо запрос ещё не завершился успешно — обновление ключа заполнит поля.

Обновить ключ

Токен Альбато, стоящий за виртуальным ключом, периодически истекает (см. выше). Когда это происходит, получите свежий токен Альбато через Embedded API с помощью вашего мастер-токена, а затем обновите существующий виртуальный ключ на месте — конфигурацию агента менять не нужно, значение mcp_vk_... не меняется:

curl -X POST <MCP_SERVER_URL>/client/keys/refresh \
  -H "Authorization: Bearer <your_registration_secret>" \
  -H "Content-Type: application/json" \
  -d '{"virtualKey": "mcp_vk_a8f3bc9d...", "albatoToken": "<fresh_albato_token>"}'

{
  "refreshed": true,
  "contractId": "acme",
  "label": "sales-agent",
  "albatoUserId": 136027,
  "albatoEmail": "user@example.com",
  "albatoName": "Jane Doe"
}

Обновление также заново определяет albatoUserId, albatoEmail и albatoName из нового токена — так заполняются поля, которые при регистрации вернулись пустыми.

Отозвать ключ

curl -X POST <MCP_SERVER_URL>/client/keys/revoke \
  -H "Authorization: Bearer <your_registration_secret>" \
  -H "Content-Type: application/json" \
  -d '{"virtualKey": "mcp_vk_a8f3bc9d..."}'

Эффект наступает немедленно: любой следующий запрос с отозванным ключом вернёт 401.

Рекомендации

• Один ключ на агента. Создавайте отдельный виртуальный ключ для каждого агента или интеграции. Если один ключ скомпрометирован, отзовите только его, не затрагивая остальные.
• Используйте метки. Всегда указывайте label, чтобы находить ключи в списке («crm-agent», «slack-bot», «onboarding-flow»). Метка описывает, для какого агента или интеграции нужен ключ, а не конечного пользователя — для этого автоматически заполняются albatoUserId, albatoEmail и albatoName.
• Задавайте срок действия для временного доступа. Передавайте expiresAt для пробных или ограниченных по времени интеграций. Истёкшие ключи отклоняются автоматически.
• Отзывайте ключи при кадровых изменениях. Если разработчик с доступом к виртуальным ключам покидает команду, немедленно отзывайте его ключи. Ваш токен Альбато при этом не затрагивается.
• Автоматизируйте обновление. Токен сессии Альбато истекает периодически (часто примерно раз в неделю). Настройте задачу по расписанию, которая получает свежий токен через Embedded API и вызывает обновление для каждого виртуального ключа, вместо того чтобы ждать ошибку 401 и регистрировать ключ заново.

Справочник ошибок