AI Agent MCP Connection Setup

Step 1: Create an AI Agent

In the DS mobile app: Settings → Team → Add Team Member → Create Agent. Enter a name and select a role. After creation you will see:

• Client ID — e.g. ds-agent-my-bot-a1b2c3d4
• Client Secret — shown once, save it immediately
• Token Endpoint — https://ds-app.biz/api/company/ai-agent/token

Step 2: Configure MCP Client

Add the following to your MCP client configuration (e.g. mcp.json in Kiro/Cursor, or Claude Desktop config):

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

Step 3: Get an Access Token

Exchange your client credentials for an access token at the agent token endpoint:

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" }

Copy accessToken into the Authorization header above.

Step 4: Verify

Test the connection by asking your AI agent to list your tasks or projects. If configured correctly, it will use the MCP tools to query Digital Specialist.

Step 5: The Agent Work Loop

Steps 1–4 connect you. This step is what makes your agent a supervised teammate rather than an anonymous API client. It is required — not optional — if you want your agent to appear on the live map, show a real status on the Fleet Console, or obey a human's Stop.

MCP is pull-only — Digital Specialist never pushes anything to your agent. Your agent therefore asks, once per iteration of its own work loop:

while (running) {
  // 1. Ask: am I paused? do I have commands waiting?
  control = call("poll-control")

  if (control.paused) {
      // Stop all side-effecting work. Keep polling — this is how you learn you were resumed.
      sleep(pollInterval); continue;
  }

  // 2. Act on any commands, then confirm each one.
  for (directive of control.directives) {
      handle(directive)                       // your logic
      call("ack-command", { directiveId: directive.id })
  }

  // 3. Tell the humans what you are doing and where you are.
  call("set-status",      { status: "working", detail: "Inspecting riser B2", workItemId: currentTaskId })
  call("report-position", { lat: 42.6977, lng: 23.3219 })

  // 4. Do one unit of real work with the business tools (create-work-item, add-work-item-comment, …)

  sleep(pollInterval)   // 30–60s is a good default
}

The four runtime tools

What poll-control returns

{
  "paused": true,
  "scope": "company",          // "company" (pause-all) | "agent" (just you) | omitted when not paused
  "directives": [
    {
      "id": "3f9a…",
      "type": "reprioritize",   // "stop" | "reprioritize" | "redirect"
      "payload": { "workItemKey": "BP-42", "priority": "High" },
      "status": "delivered",
      "issuedByUserId": "8c21…",
      "createdOn": "2026-08-11T09:14:03Z"
    }
  ]
}

Directives

A directive only instructs you. Anything you then do still passes the company's approval policy and your own permissions — a directive is never an authorisation.

Staying alive on the roster

An agent that has made no call for 5 minutes is marked Offline automatically. Any authenticated MCP call counts as a heartbeat — including poll-control — so an agent that is idle but still polling stays online, and one that is waiting on a human approval does too. If your loop can sleep longer than five minutes, poll anyway.

Step 6: Asking a Human

Some actions need a person. Digital Specialist gives you three ways to involve one, and they are the difference between an agent that stalls and one that hands off cleanly.

Approval before a guarded action

Your company can require human approval for certain action types. Rather than attempting the write and being refused, ask first:

// 1. Ask. Returns a requestId.
call("request-approval", {
  intensity: "review",              // "notify" | "question" | "review"
  actionType: "create_task",
  summary: "Create a task to replace the corroded valve on B2",
  proposedPayload: "{\"title\":\"Replace valve\",\"projectKey\":\"BP\"}",
  workItemId: null
})

// 2. Poll for the outcome. Keep polling — this counts as a heartbeat, so you will not be reaped.
call("get-approval-status", { requestId })

The human can Accept, Edit (accept a modified payload — get-approval-status then returns the version they edited, and that is the one you must run), Respond with a free-text answer, or ignore it. Set intensity honestly: review puts your proposal in front of a manager as a full preview, notify is a passing mention.

Handing a task to a person

When you are not confident enough to finish something, hand it over rather than guessing:

call("escalate-task", {
  workItemId: "…",
  targetUserId: "…",                // must be able to access that task's project
  reason: "Cannot identify the part number from the photo",
  confidence: 0.35,
  summary: "Tried OCR and the parts catalogue; two candidate SKUs remain."
})

The system builds a context package from your recent activity, reassigns the task, notifies the person, and shows the hand-off on the map.

Integration Checklist

A conforming agent does all of the following. If you can tick every line, your agent will behave correctly on the Fleet Console, the live map, and under a human's supervision.

• Requests a fresh access token before the current one expires; retries once on 401.
• Calls poll-control at least once every 5 minutes, even when idle.
• Stops all side-effecting work while paused is true, and keeps polling until it clears.
• Handles every directive idempotently and calls ack-command afterwards.
• Reports set-status and report-position as they change.
• Uses request-approval for guarded actions instead of retrying refused writes.
• Uses escalate-task instead of guessing when confidence is low.
• Reports only outcomes the tool response confirmed.

Available Tool Groups

The MCP server provides these tool groups:

That is 94 tools across 17 groups. Your MCP client discovers the exact catalogue at runtime — this table is orientation, not a contract.

Permissions

Agent permissions are set during creation and control what the agent can do:

The agent's role (Admin, Manager, Specialist, Observer) also controls what data it can access, same as for human users. For example, a Specialist agent can only see public projects and private projects where it is a member.