Skip to the content

DocumentationAI assistants

Developer tools

AI assistants

Letting an AI assistant read and act within limits

Step 5.10 of the plan (P5, C5.6, C12, U-14).

A developer working a handover can let a coding assistant (Claude Code, Cursor, or another assistant that speaks MCP) read that handover's evidence, so the assistant starts from the same facts the developer has. The access is read-only, covers one handover, expires, and every use is logged. It never includes credentials and never reaches production.

Granting

On the handover's page, the developer it is assigned to opens Coding assistants. They name the assistant and choose how long the access lasts, from 1 hour to 7 days. This works while the handover is being worked (Accepted, Investigating, Waiting for information).

OpsCommand shows the token (oca_…) once, inside a ready-made MCP configuration. It keeps only the token's SHA-256. The grant is listed with its status and every use the assistant made. Whoever granted it, or someone with organisation.manage, can Revoke it at once.

What the assistant can read

PartWhat it holds
handoverThe handover's fields, in the brief's order: environment, reproduction steps, expected and actual behaviour, error messages, logs, correlation IDs, when it occurred, affected users, business impact, troubleshooting so far, possible causes, areas to investigate. It also lists the fields declared not available, each with its reason.
evidenceThe events, logs and errors collected into the handover (5.2).
codeThe issues, pull or merge requests and commits linked to the handover (5.4, 5.5).
attachmentsThe names, types, sizes and SHA-256 of the attachments, never their contents.

Every answer passes through OpsCommand's redaction on the way out. Tokens, keys, passwords and personal data that slipped into a field are masked, as they are everywhere else (U-07).

What it cannot do

  • Read anything else. A request for another handover — by number or by ID, in this organisation or another — is refused, and so is any other part. The refusal is logged with what was asked for.
  • Read after expiry or revocation. These requests are refused and logged too.
  • Change anything. The token opens only GET /v1/assistant/…. It is not a sign-in, so every other route answers 401, and no function a token reaches writes anything.
  • Reach credentials or production. Code-host tokens, ingest keys, webhook secrets and attachment contents are not in any part.

The rules are the database's (dev.grant_assistant, dev.revoke_assistant, dev.assistant_read in migration 0041_assistant_access). The log (dev.assistant_access) is append-only.

The MCP server

apps/mcp is OpsCommand's MCP server. It speaks the Model Context Protocol over stdio and runs on the developer's machine. It has four tools, all marked read-only: get_handover, get_evidence, get_code and list_attachments. Each takes an optional handover; left out, it means the granted one. A refusal comes back as a tool error, so the assistant sees why.

{
  "mcpServers": {
    "opscommand": {
      "command": "npx",
      "args": ["@opscommand/mcp"],
      "env": { "OPSCOMMAND_API_URL": "https://api.opscommand.dev", "OPSCOMMAND_ASSISTANT_TOKEN": "oca_…" }
    }
  }
}

The server reads the token only from its environment and never prints it. It refuses an API address that is not https (plain http is allowed only on the same machine).

The API

An assistant can also use the API directly, with the token as a Bearer token:

  • GET /v1/assistant/handover: the granted handover.
  • GET /v1/assistant/handovers/{handover}/{part}, where part is handover, evidence, code or attachments.

These calls are limited to 120 a minute per token. The developer's routes (signed in) are:

  • GET /v1/organisations/{org}/handovers/{handover}/assistant-grants
  • POST …/assistant-grants ({ name, hours })
  • DELETE …/assistant-grants/{grant}