MCP server

Rahdar speaks the Model Context Protocol, so an assistant can answer "why is ORDERS.DLQ backed up" against your real clusters instead of guessing.

The surface is sixteen intent-shaped tools — diagnose, message_action, broker_config_change — not a mirror of the REST API. A mirror would spend the model's context on plumbing and leave it to assemble the diagnosis; the tools are shaped like the questions instead (ADR-0045).

Get a key

Sign in → avatar menu → Account → API keys → New key → choose when it expires, the scope and permissions it carries, and optionally the MCP tools it may call → copy the value. It is shown once.

• Expiry. Every key expires, at most the installation's maximum lifetime after it was minted (90 days by default, Settings → API tokens → Maximum lifetime). Lowering the maximum shortens existing keys at once.
• Tools. A key restricted to named tools is offered only those, plus rahdar_help. The other tools are not listed or described to it, and calling one answers exactly as a tool that does not exist.
• Rotation. Rotate issues a new secret and keeps the old one working for the rotation overlap (24 hours by default), so an assistant's configuration can be updated without an outage. The key keeps its permissions and its expiry.
• Limits. A key may make 600 requests a minute with 8 in flight, and one user 1,200 a minute across all their keys. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and an excess request gets 429 with Retry-After.
• Usage shows each key's requests per day, with how many were denied, limited or failed. Administrators with See and revoke every user's API tokens see every key under Admin → API keys, where unused keys are flagged and any key can be revoked (ADR-0136).

Connect

POST /mcp, on the same origin as the UI, with the key as a bearer token.

{
  "mcpServers": {
    "rahdar": {
      "type": "http",
      "url": "https://rahdar.example.com/mcp",
      "headers": { "Authorization": "Bearer as_..." }
    }
  }
}

Smoke-test it without a client:

curl -s https://rahdar.example.com/mcp \
  -H "Authorization: Bearer as_..." \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

scripts/mcp-config-e2e.sh drives the whole configuration loop over this wire — handshake, tools/list, declare, plan, refuse a stale plan, apply, converge, and every read kind — against the dev stack, and removes what it applied so it can be run again.

What is there

Kind	Name	For
Tool	rahdar_help	the catalogue itself: every tool, its posture and its parameters
Tool	diagnose	a cluster (HA role per node, split-brain, replication lag, firing alerts) or one queue end to end
Tool	list_resources	queues, addresses, consumers, sessions, connections, producers, diverts, bridges
Tool	metric_series	a bucketed timeseries for one metric
Tool	config_diff	every node's configuration against the majority: the keys that drift and the nodes that differ
Tool	broker_config	the cluster's declaration, its drift per node, the broker.xml fragment, or past applies
Tool	browse_messages	headers, or one body by id
Tool	trace_request_reply	flows, latency and timeout statistics, configured expectations
Tool	activity_log	broker events, or Rahdar's own audit trail
Tool	message_action	move / retry / delete / expire / purge
Tool	queue_lifecycle	create, update, pause, resume or destroy a queue, address or divert
Tool	broker_config_change	declare a configuration, or apply it canary-first with hazards acknowledged by id
Tool	connection_action	close a connection, session, consumer or an address's consumers
Tool	send_message	enqueue one message
Tool	alert_rule / rahdar_setting	alert rules; operational settings
Resource	rahdar://clusters, rahdar://permissions, rahdar://tools	what this key can see and do
Resource	cluster://{id}/topology, cluster://{id}/capabilities, cluster://{id}/nodes/{nodeId}/settings	nodes; what the connection supports, with the broker.xml to enable what it does not; one node's effective settings
Prompt	triage_cluster, investigate_queue, before_you_purge, tune_scrape_load	runbooks

The safety contract

An assistant with a management API is exactly where a safety model needs to be boring and explicit. This one is:

• A key never exceeds its owner. Grants are intersected with the owner's live grants on every call, so narrowing a person narrows their keys at once (ADR-0046).
• Mutations dry-run by default. A real destructive run additionally requires confirm to equal the queue's own name — separate from the bulk-cap override, which answers a different question and is never satisfied by confirm.
• A configuration apply is the same contract at cluster scale. The dry run returns the plan, its hazards and the exact acknowledge ids a real run must echo; the real run needs confirm to equal the cluster's name and expectedPlanHash to equal the hash it previewed, goes canary first and halts at the first failure. See Broker configuration.
• Every call is audited, reads included, as MCP_TOOL_CALL under the owner with the key's name attached (ada [token: laptop-agent]), naming the tool, the cluster and the outcome. The rows a mutation writes, dry runs included, hang under it (ADR-0137).
• The installation can be made read-only. Settings → MCP server → Read-only hides every mutating tool and refuses it for every key, whatever its confirm. A single read-only key is simply a key granted only read permissions.
• A cluster the key holds no grant on comes back as "no such cluster, or this key has no grant on it" — naming no permission and confirming no id.

Discovery

rahdar_help is a tool, not an optional resource, and one catalogue generates the schemas, the help text, the resource and the server instructions — so they cannot disagree (ADR-0054).