API tokens and MCP server
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.
claudeorci-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?"
| Tool | What it does | Role |
|---|---|---|
list_clusters | the cluster entries this Warren watches | viewer |
list_queues | queues of a cluster, dead-letter queues first, with counts and consumers | viewer |
failures | dead letters across the cluster grouped by exception, or by reason and queue, as on the Failures page | viewer |
failure_report | the incident report of one failure as Markdown: first and last seen, notes, actions, outcome | viewer |
peek_messages | up to 50 messages from the head of a queue, without taking them | viewer |
queue_settings | the policy in force, the ones it outranks, every dead-letter and limit setting with its origin, where the dead letters go | viewer |
setup_checks | the set-up checks: queues without a dead-letter exchange, routes into nowhere, quorum limits | viewer |
plan_replay | a 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 minutes | operator |
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.