Integrations

Connect your agents to Waitroom through whichever integration fits your stack — MCP, SDK, REST, or Python.

MCP Server

The Waitroom MCP server exposes 6 tools that any MCP-compatible client can call. It handles authentication and polling automatically.

Claude Code

Add MCP server to Claude Code

$ claude mcp add waitroom \
  --transport sse \
  --url https://mcp.waitroom.io/sse \
  -e WAITROOM_API_KEY=wr_your_key_here

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

.cursor/mcp.json

{
  "mcpServers": {
    "waitroom": {
      "url": "https://mcp.waitroom.io/sse",
      "env": {
        "WAITROOM_API_KEY": "wr_your_key_here"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

claude_desktop_config.json

{
  "mcpServers": {
    "waitroom": {
      "command": "npx",
      "args": ["@waitroom-io/mcp-server"],
      "env": {
        "WAITROOM_API_KEY": "wr_your_key_here",
        "API_BASE_URL": "https://api.waitroom.io"
      }
    }
  }
}

MCP Tools

Tool	Description	Key Parameters
waitroom_check_in	Check in with a human for approval. Optionally waits for decision.	room, action, risk_level, urgency, context, wait_for_decision
waitroom_check_status	Poll the status of an existing check-in.	check_in_id
waitroom_watch	Subscribe to watch for events in a room.	room, event_types, webhook_url
waitroom_signal	Broadcast a signal to all watchers in a room.	room, type, payload
waitroom_list_rooms	List all rooms in the organization.	(none)
waitroom_withdraw	Withdraw a pending check-in request.	check_in_id

Self-Hosting

To self-host the MCP server, clone the repo and run it locally:

Self-host MCP server

$ git clone https://github.com/waitroom-io/waitroom
$ cd waitroom/apps/mcp-server
$ cp .env.example .env
# Edit .env: set API_BASE_URL and WAITROOM_API_KEY
$ pnpm install && pnpm dev

Waitroom MCP Server running on port 3002
SSE endpoint: http://localhost:3002/sse

TypeScript SDK

Installation

Install

$ npm install @waitroom-io/sdk # or pnpm / yarn / bun

Initialize

client.ts

import { WaitroomClient } from '@waitroom-io/sdk'

const client = new WaitroomClient({
  apiKey: process.env.WAITROOM_API_KEY,
  baseUrl: 'https://api.waitroom.io'
})

Resource Methods

The SDK provides typed resource accessors:

SDK usage examples

// Create a check-in
const checkIn = await client.checkIns.create('default', {
  action: 'Deploy to production',
  risk_level: 'high',
  urgency: 'normal'
})

// List rooms
const rooms = await client.rooms.list()

// Broadcast a signal
await client.signals.broadcast('default', {
  type: 'config_update',
  payload: { feature: 'dark_mode', enabled: true }
})

// Create a watcher
await client.watchers.create('default', {
  event_types: ['signal.broadcast']
})

Check-in and Wait

The SDK includes a checkInAndWait() helper that creates a check-in and polls for a decision with exponential backoff:

Check-in and wait for decision

const decision = await client.checkIns.checkInAndWait('default', {
  action: 'Send invoice to client',
  risk_level: 'medium'
})

if (decision.status === 'approved') {
  // Proceed with the action
} else if (decision.status === 'modified') {
  // Apply modifications from decision.modifications
} else {
  // Rejected or expired — read decision.decision_reason
}

Error Handling

The SDK throws typed errors that map to HTTP status codes:

Error handling

try {
  await client.checkIns.create('room', { ... })
} catch (err) {
  // err.code    — "POLICY_FORBIDS"
  // err.message — human-readable
  // err.statusCode — 403
}

REST API

Use the REST API directly from any language. See the full API Reference for all endpoints. Here is a common flow:

Create and Poll a Check-in

curl — create + poll

# 1. Create a check-in
$ CHECKIN=$(curl -s -X POST https://api.waitroom.io/v1/rooms/default/check-in \
  -H "Authorization: Bearer $WAITROOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"Delete old backups","risk_level":"high"}')

# 2. Extract check-in ID
$ ID=$(echo $CHECKIN | jq -r '.data.id')

# 3. Poll for decision
$ curl -s https://api.waitroom.io/v1/check-ins/$ID/status \
  -H "Authorization: Bearer $WAITROOM_API_KEY"

Python

Use the requests library to call the Waitroom API from Python:

waitroom_client.py

import requests, time, os

API_KEY = os.environ["WAITROOM_API_KEY"]
BASE = "https://api.waitroom.io/v1"
HEADERS = {
  "Authorization": f"Bearer {API_KEY}",
  "Content-Type": "application/json"
}

def check_in_and_wait(room, action, risk_level="medium"):
  # Create check-in
  resp = requests.post(
    f"{BASE}/rooms/{room}/check-in",
    headers=HEADERS,
    json={"action": action, "risk_level": risk_level}
  )
  ci = resp.json()["data"]

  # Poll with exponential backoff
  interval = 1
  while ci["status"] == "pending":
    time.sleep(interval)
    interval = min(interval * 1.5, 30)
    r = requests.get(
      f"{BASE}/check-ins/{ci['id']}/status",
      headers=HEADERS
    )
    ci = r.json()["data"]

  return ci

Tip

Use exponential backoff when polling. Start at 1 second, multiply by 1.5x each iteration, cap at 30 seconds. The SDK handles this automatically.