Warren
Automate

API tokens and MCP server

CommunityTeamPro

Scripts and AI agents use Warren the way you do: with your account, your role and the same audit log. An API token lets them in without a password, and the MCP server gives agents tools to find out what failed and what a replay would take.

Create a token

Open the account menu (your name, top right) and choose API tokens:

  • Name: what uses it, e.g. claude or ci-replay.
  • Role: read only (viewer) or operator, never more than your own role. A token for an agent that only looks needs no more than viewer.
  • Expires: 30 days, 90 days, a year, or not at all.

Warren shows the token once, as wrn_…; only its first characters stay visible in the list, with when it was last used. Revoke ends it at once. Admins see and revoke everyone's tokens with GET /api/tokens/all and DELETE /api/tokens/{id}.

A token follows its owner's account: when an admin disables a user or lowers their role, their tokens lose access or the role with it, and deleting a user deletes their tokens. For users who sign in with single sign-on, the role is the one the token got when it was created; revoke it when someone leaves.

Use it with the REST API

Send the token in the Authorization header. Every endpoint the UI uses works, under the token's role:

export WARREN=https://warren.example.com
export TOKEN=wrn_…
curl -H "Authorization: Bearer $TOKEN" $WARREN/api/clusters
curl -H "Authorization: Bearer $TOKEN" $WARREN/api/clusters/prod/failures

A replay of the first 20 messages of a queue, with a dry run first:

PLAN=$(curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind":"REPLAY","selection":{"type":"COUNT","count":20}}' \
  $WARREN/api/clusters/prod/queues/orders.dlq/plans | jq -r .id)
curl -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"selection\":{\"type\":\"PLAN\",\"plan\":\"$PLAN\"},\"target\":{\"type\":\"ORIGINAL\"}}" \
  $WARREN/api/clusters/prod/queues/orders.dlq/replay

The audit log records the token's owner as the one who acted. A token cannot create other tokens; that takes the UI. Requests with a token create no session.

Connect an AI agent (MCP)

Warren serves the Model Context Protocol at /mcp (Streamable HTTP). It takes API tokens only, not a browser session.

Claude Code:

claude mcp add --transport http warren https://warren.example.com/mcp \
  --header "Authorization: Bearer wrn_…"

Cursor (.cursor/mcp.json) and VS Code (.vscode/mcp.json, with "servers" and "type": "http"):

{
  "mcpServers": {
    "warren": {
      "url": "https://warren.example.com/mcp",
      "headers": { "Authorization": "Bearer wrn_…" }
    }
  }
}

Then ask in plain words: "What is failing in prod right now?", "Why does orders.work not dead-letter?", "How many OrderNotFoundException messages in orders.dlq would a replay take?"

ToolWhat it doesRole
list_clustersthe cluster entries this Warren watchesviewer
list_queuesqueues of a cluster, dead-letter queues first, with counts and consumersviewer
failuresdead letters across the cluster grouped by exception, or by reason and queue, as on the Failures pageviewer
failure_reportthe incident report of one failure as Markdown: first and last seen, notes, actions, outcomeviewer
peek_messagesup to 50 messages from the head of a queue, without taking themviewer
queue_settingsthe policy in force, the ones it outranks, every dead-letter and limit setting with its origin, where the dead letters goviewer
setup_checksthe set-up checks: queues without a dead-letter exchange, routes into nowhere, quorum limitsviewer
plan_replaya dry run of a replay to the original route: the first N, or every message matching reasons or text; returns the count and a plan id, valid for 10 minutesoperator

Nothing an agent does moves a message. plan_replay only freezes which messages a replay would take, for 10 minutes; a person runs it, in Warren or with the REST API as above. Reading a quorum dead-letter queue where a read would count as a delivery is refused with the reason, as in the UI.