CLI & MCP server

@roundtrip/mcp is a Model Context Protocol server for AI agents. It wraps @roundtrip/sdk, so an agent can send a notification, ask for human approval, list channels, and read the status of a notification it sent.

Register the server

claude mcp add roundtrip \
  --env ROUNDTRIP_API_KEY=ak_xxx \
  --env ROUNDTRIP_BASE_URL=https://api.roundtrip.sh \
  -- npx -y @roundtrip/mcp

ROUNDTRIP_API_KEYak_...required

A workspace API key. New keys include notifications:write, notifications:read, and channels:read.

ROUNDTRIP_BASE_URLurlrequired

Your deployment host, for example https://api.roundtrip.sh.

Tools

send_requesttooloptional

General structured notification. Supply push plus optional content, detail, response, metadata, and idempotency_key.

request_human_approvaltooloptional

Shortcut for approve/reject decisions. Builds content actions with stable approve and reject ids and returns a notification id immediately.

get_request_statustooloptional

Reads the current notification snapshot, named slots, append history, and responses by notification id.

list_channelstooloptional

Lists channels available to the API key.

Agent prompts

These are prompts you can give the agent after the MCP server is registered.

Send a Roundtrip notification to the "deploys" channel:
push title "Deploy finished" and body "v2.4.1 is live in production."

`send_request`

send_request is the general tool. Its name stays stable for agents, but the payload is the notification API shape:

tool input

{
  "channel": "on-call",
  "push": {
    "title": "Checkout latency is high",
    "body": "p95 crossed 2.4s",
    "priority": "high"
  },
  "content": {
    "title": "Checkout latency",
    "description": "Investigating elevated p95 latency.",
    "status": "warning"
  },
  "metadata": { "incidentId": "inc_42" },
  "idempotency_key": "incident-inc_42-open"
}

`request_human_approval`

The approval shortcut fills in an approve/reject card for the agent:

channelstringrequired

The channel to publish into.

titlestringrequired

The decision, phrased as a clear question.

bodystringoptional

One-line summary used as push body and content description.

detailsstringoptional

Markdown context rendered in the detail screen.

contextobjectoptional

Metadata echoed back in the signed webhook event.

webhookurloptional

Where the signed response event is posted.

The tool does not block

The tool returns the notification id immediately. The actual human decision arrives later as a signed response.submitted webhook event.

Local development

Run from source

ROUNDTRIP_API_KEY=ak_xxx \
ROUNDTRIP_BASE_URL=https://api.roundtrip.sh \
pnpm --filter @roundtrip/mcp dev

stdout is sacred

MCP uses stdout for the protocol stream. Debug logging must go to stderr.

Next steps

Notification workflows

SDK patterns for long-running workflows and webhooks.

Quickstart

Send and update notifications directly with curl.