Настройка на 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 клиент получава точния каталог по време на изпълнение — тази таблица е за ориентация, не е договор.

Разрешения

Разрешенията на агента се задават при създаването и определят какво може да прави:

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