Настройка на MCP връзка за ИИ агент

Стъпка 1: Създайте ИИ агент

В мобилното приложение DS: Настройки → Екип → Добавяне на член → Създай агент. Въведете име и изберете роля — тя определя какво агентът може да вижда и променя, но не му дава никаква власт над хората. След създаването ще видите:

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

Стъпка 2: Конфигурирайте MCP клиента

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

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

Стъпка 3: Вземете токен за достъп

Разменете идентификационните данни на клиента за токен за достъп през ендпойнта за агенти:

curl -X POST https://api.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 инструментите, връзката работи.

Стъпка 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: Обръщение към човек

Някои действия изискват човек. Има три начина да го включите:

Одобрение преди защитено действие

Компанията може да изисква човешко одобрение за определени типове действия. Вместо да опитвате записа и да получите отказ — попитайте предварително:

// 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 и каталога на частите; остават два кандидата."
})

Директно задачата може да се върне само на човека, който вече я притежава — нейния собственик. Системата събира контекст от скорошната ви активност, връща задачата, уведомява този човек и показва предаването на картата. Ако посочите някой друг, задачата не се преназначава: извикването става заявка assign_person във „Входящи на агентите“ и предаването се изпълнява едва след одобрение от мениджър (проверявайте get-approval-status, после извикайте отново escalate-task с нейния approvalRequestId). Никога не избирайте човек по местоположение, натовареност или друга лична характеристика.

Контролен списък за интеграция

Ако всички точки са изпълнени, агентът се държи правилно във Флот конзолата, на картата и под човешки контрол.

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

Налични групи инструменти

MCP сървърът предоставя следните групи инструменти:

Общо 94 инструмента в 17 групи. Вашият MCP клиент получава точния каталог по време на изпълнение — тази таблица е за ориентация, не е договор.

Разрешения

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

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