Настройка MCP-подключения для ИИ-агента

Шаг 1: Создайте ИИ-агента

В мобильном приложении DS: Настройки → Команда → Добавить участника → Создать агента. Введите имя и выберите роль. После создания вы увидите:

• Client ID — например ds-agent-my-bot-a1b2c3d4
• Client Secret — показывается один раз, сохраните сразу
• Token Endpoint — https://ds-app.biz/api/company/ai-agent/token

Шаг 2: Настройте MCP-клиент

Добавьте следующее в конфигурацию вашего MCP-клиента (например, mcp.json в Kiro/Cursor или конфиг Claude Desktop):

{
  "mcpServers": {
    "digital-specialist": {
      "type": "streamableHttp",
      "url": "https://ds-app.biz/mcp",
      "headers": {
        "Authorization": "Bearer <ACCESS_TOKEN>"
      }
    }
  }
}

Шаг 3: Получите токен доступа

Обменяйте учётные данные клиента на токен доступа через эндпоинт для агентов:

curl -X POST https://ds-app.biz/api/company/ai-agent/token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET"}'

# → { "accessToken": "eyJ…", "expiresIn": 3600, "tokenType": "Bearer" }

Скопируйте accessToken в заголовок Authorization выше.

Шаг 4: Проверьте подключение

Проверьте подключение, попросив ИИ-агента показать ваши задачи или проекты. Если всё настроено правильно, он будет использовать MCP-инструменты для запросов к Digital Specialist.

Шаг 5: Рабочий цикл агента

Шаги 1–4 подключают вас. Этот шаг превращает агента в подконтрольного члена команды, а не в анонимного API-клиента. Он обязателен — не опционален — если вы хотите, чтобы агент появлялся на карте, показывал реальный статус в Консоли флота и подчинялся команде «Стоп» от человека.

MCP работает только на запросах агента — Digital Specialist ничего не отправляет агенту сам. Поэтому агент спрашивает сам, один раз за итерацию своего рабочего цикла:

while (running) {
  // 1. Спросить: я на паузе? есть ли команды?
  control = call("poll-control")

  if (control.paused) {
      // Прекратить любые изменяющие действия. Продолжать опрос — так вы узнаете о возобновлении.
      sleep(pollInterval); continue;
  }

  // 2. Выполнить команды и подтвердить каждую.
  for (directive of control.directives) {
      handle(directive)                       // ваша логика
      call("ack-command", { directiveId: directive.id })
  }

  // 3. Сообщить людям, что вы делаете и где находитесь.
  call("set-status",      { status: "working", detail: "Осмотр стояка B2", workItemId: currentTaskId })
  call("report-position", { lat: 42.6977, lng: 23.3219 })

  // 4. Выполнить одну единицу работы бизнес-инструментами (create-work-item, add-work-item-comment, …)

  sleep(pollInterval)   // 30–60 с — хорошее значение по умолчанию
}

Четыре инструмента рабочего цикла

Что возвращает poll-control

{
  "paused": true,
  "scope": "company",          // "company" (пауза всех) | "agent" (только вы) | отсутствует, если не на паузе
  "directives": [
    {
      "id": "3f9a…",
      "type": "reprioritize",   // "stop" | "reprioritize" | "redirect"
      "payload": { "workItemKey": "BP-42", "priority": "High" },
      "status": "delivered",
      "issuedByUserId": "8c21…",
      "createdOn": "2026-08-11T09:14:03Z"
    }
  ]
}

Директивы

Директива только указывает. Всё, что вы затем делаете, всё равно проходит политику согласования компании и ваши права — директива никогда не является разрешением.

Как оставаться в сети

Агент, не сделавший ни одного вызова в течение 5 минут, автоматически помечается как Оффлайн. Любой аутентифицированный MCP-вызов считается сигналом активности — включая poll-control, — поэтому простаивающий, но опрашивающий агент остаётся в сети, как и агент, ожидающий согласования. Если ваш цикл может спать дольше пяти минут, всё равно опрашивайте.

Шаг 6: Обращение к человеку

Некоторые действия требуют человека. Digital Specialist даёт три способа его привлечь — именно они отличают агента, который зависает, от агента, который корректно передаёт работу.

Согласование перед защищённым действием

Компания может требовать согласования для определённых типов действий. Вместо попытки записи с последующим отказом — спросите заранее:

// 1. Запросить. Возвращает requestId.
call("request-approval", {
  intensity: "review",              // "notify" | "question" | "review"
  actionType: "create_task",
  summary: "Создать задачу на замену корродированного клапана на B2",
  proposedPayload: "{\"title\":\"Заменить клапан\",\"projectKey\":\"BP\"}",
  workItemId: null
})

// 2. Опрашивать результат. Опрос также считается сигналом активности.
call("get-approval-status", { requestId })

Человек может Принять, Изменить (принять изменённый payload — тогда get-approval-status вернёт именно отредактированную версию, и выполнять нужно её), Ответить свободным текстом или проигнорировать. Указывайте intensity честно: review показывает предложение руководителю целиком, notify — лишь упоминание.

Передача задачи человеку

Если уверенности недостаточно — передайте задачу, а не угадывайте:

call("escalate-task", {
  workItemId: "…",
  targetUserId: "…",                // должен иметь доступ к проекту этой задачи
  reason: "Не удаётся определить артикул по фотографии",
  confidence: 0.35,
  summary: "Пробовал OCR и каталог деталей; остались два кандидата."
})

Система соберёт контекст из вашей недавней активности, переназначит задачу, уведомит человека и покажет передачу на карте.

Чек-лист интеграции

Соответствующий требованиям агент делает всё перечисленное. Если выполнены все пункты, агент будет корректно вести себя в Консоли флота, на карте и под контролем человека.

• Запрашивает новый токен до истечения текущего; один раз повторяет попытку при 401.
• Вызывает poll-control не реже одного раза в 5 минут, даже в простое.
• Прекращает любые изменяющие действия, пока paused истинно, и продолжает опрос до снятия паузы.
• Обрабатывает каждую директиву идемпотентно и вызывает затем ack-command.
• Сообщает set-status и report-position при изменениях.
• Использует request-approval для защищённых действий вместо повтора отклонённых записей.
• Использует escalate-task вместо догадок при низкой уверенности.
• Сообщает только те результаты, которые подтвердил ответ инструмента.

Доступные группы инструментов

MCP-сервер предоставляет следующие группы инструментов:

Всего 94 инструмента в 17 группах. Ваш MCP-клиент получает точный каталог во время выполнения — эта таблица для ориентира, а не контракт.

Разрешения

Разрешения агента задаются при создании и определяют доступные действия:

Роль агента (Администратор, Руководитель, Специалист, Наблюдатель) также определяет доступ к данным — так же, как и для обычных пользователей. Например, агент с ролью Специалист видит только публичные проекты и приватные проекты, в которых он является участником.