MCP (Claude Code, Claude Desktop, Cursor)

clrd serves MCP at https://clrd.itsjustin.me/mcp (streamable HTTP, stateless). Auth is the same Bearer token as the REST API; the token's scopes and topic allow-list apply, and actions show up as made by that token's device.

Tools:

Tool Arguments Does
send topic, message, title?, priority?, id?, actions? Publish. id is your stable key (external_id). actions adds up to 3 answer buttons, [{"label":"Yes","reply":"yes"}].
list topic?, state? List, default open.
ack id Acknowledge by server id.
resolve id or topic + external_id Clear it everywhere.
snooze id, for Snooze, e.g. for: "1h".
wait_for_reply id, timeout_s? Block until a human acks or dismisses it, or it is resolved. Snooze keeps it waiting. Returns reply = the new state, or timeout, plus answer when a button from actions was tapped. Default 60 s, max 300 s.

wait_for_reply returns at once if the notification is already acknowledged, dismissed or resolved. Otherwise it watches the server's committed events, so an ack that is quickly followed by a snooze is still reported as an ack.

wait_for_reply is how an agent asks a human "OK to deploy?" and waits:

send {"topic": "agents", "message": "OK to deploy?", "id": "deploy-1",
      "actions": [{"label": "Yes", "reply": "yes"}, {"label": "No", "reply": "no"}]}
wait_for_reply {"id": "<id from send>", "timeout_s": 300}
-> {"reply": "acknowledged", "answer": "yes", "by": "pixel-9", "notification": {...}}

The first tap wins; a second phone gets told it is already answered. A plain ack (no button) has no answer, and dismiss means no. The web inbox and the Android app show the buttons once they support them (issue 8); until then a human can still ack or dismiss.

Claude Code

claude mcp add --transport http clrd https://clrd.itsjustin.me/mcp \
  --header "Authorization: Bearer clrd_..."

Claude Desktop

claude_desktop_config.json, through the mcp-remote bridge:

{
  "mcpServers": {
    "clrd": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://clrd.itsjustin.me/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer clrd_..." }
    }
  }
}

(No spaces around the colon in Authorization:${AUTH_HEADER}; that is an mcp-remote workaround for Windows argument escaping.)

Cursor

.cursor/mcp.json (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "clrd": {
      "url": "https://clrd.itsjustin.me/mcp",
      "headers": { "Authorization": "Bearer ${env:CLRD_TOKEN}" }
    }
  }
}

Auto-resolve

Have the agent call send with an id when it starts something risky, and resolve with topic and external_id when it is done. Checked with the MCP Inspector CLI; the Desktop and Cursor snippets follow their upstream docs and are untested against a live clrd.