PingRoom Agent API & MCP

Choose a connection path

Use the hosted MCP endpoint for Claude or Cursor, or app pairing for the CLI and the SDK. Each path ends with a scoped, revocable connection; none asks you to paste an API token.

npm install -g @pingroom/cli
pingroom
# Scan the QR code or open the link, then choose a room and approve in PingRoom

pingroom ping -m "CLI connected"

claude mcp add --transport http pingroom https://api.pingroom.io/api/agent/mcp

import { PingRoom } from '@pingroom/sdk';

const pingroom = new PingRoom();
const pairing = await pingroom.auth.startPairing({
  agent_label: 'Deploy bot',
  scopes: [
    'pingroom:rooms:read',
    'pingroom:broadcast:send',
    'pingroom:handoffs:create',
  ],
});

console.log('Open in PingRoom:', pairing.pair_url);
const connection = await pingroom.auth.waitForPairing(pairing);
const activation = await pingroom.inbox.activate({
  overallTimeoutMs: 120_000,
});

console.log('Agent Inbox ready:', activation.activation_completed);

await pingroom.broadcast(connection.room.invite_code, {
  message: 'SDK connected',
});

Discovery

The machine-readable description of how to register lives at pingroom.io/auth.md. An agent that hits a protected endpoint without a credential gets a 401 with a WWW-Authenticate header pointing to protected-resource metadata; that document names the authorization server:

• /.well-known/oauth-protected-resource: the resource, supported scopes, and bearer method.
• /.well-known/oauth-authorization-server: the authorization, token, and dynamic registration endpoints.

Registering

Registration binds an agent credential to a person’s account. An agent cannot gain access on its own. There is always proof of a real human in the chain. PingRoom supports three flows at POST /api/agent/auth:

• Verified (ID-JAG): the agent presents a token signed by a trusted identity provider, audience-scoped to PingRoom. Verified against the provider’s public keys; an active credential is issued synchronously.
• Verified email: the agent presents a provider token proving the user’s email. If it matches an existing account, an active credential is issued.
• Anonymous + claim: the agent receives a short-lived, scope-less pre-claim credential and the user completes a one-time email code to bind it.

The credential is a bearer token presented as Authorization: Bearer <credential> on every request. A user can see and revoke connected agents from the app’s Connected Agents screen at any time.

Raw REST registration

This lower-level flow is for custom clients that manage credentials themselves. The CLI and the SDK both use app pairing, and MCP hosts should use OAuth. For verified REST flows, replace steps 1 to 3 with a single POST /api/agent/auth carrying your provider assertion, and you get an active credential back immediately.

# 1. Register (anonymous). Returns a short-lived pre-claim credential
curl -sX POST https://api.pingroom.io/api/agent/auth \
  -H 'Content-Type: application/json' \
  -d '{"type":"anonymous","scopes":["pingroom:rooms:write","pingroom:actions:trigger","pingroom:profile:write","pingroom:handoffs:create"],"agent_label":"My Agent"}'
# → { "credential": "<pre-claim JWT>", "credential_type": "pre_claim", "expires_in": 900, "claim": {...} }

PRECLAIM="<pre-claim JWT>"

# 2. Start the claim. Emails the user a one-time code
curl -sX POST https://api.pingroom.io/api/agent/auth/claim/start \
  -H "Authorization: Bearer $PRECLAIM" -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

# 3. Complete the claim with the code the user reads back. Returns the ACTIVE credential
curl -sX POST https://api.pingroom.io/api/agent/auth/claim/complete \
  -H "Authorization: Bearer $PRECLAIM" -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","otp":"123456"}'
# → { "credential": "<active JWT>", "credential_type": "active", "expires_in": null }

TOKEN="<active JWT>"

# 4a. Set a bot avatar
curl -sX POST https://api.pingroom.io/api/agent/profile/avatar \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"avatar_id":"bots-3"}'

# 4b. Create a room (free accounts: up to five rooms)
curl -sX POST https://api.pingroom.io/api/agent/rooms \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"Build Alerts","icon":"bell","color":"#e33122"}'

# 4c. Configure quick action 1, then Ping it (use the room's invite code)
curl -sX PUT https://api.pingroom.io/api/agent/rooms/ABC123/actions/1 \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"label":"Deploy done","icon":"🚀","sound":"ting"}'

curl -sX POST https://api.pingroom.io/api/agent/rooms/ABC123/actions/1/trigger \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"trigger_source":"manual"}'

What agents can do

Each capability is gated by a granular scope on the credential. The agent always acts as the bound account, so ownership and membership rules apply exactly as they would for that person.

{ "name": "Build Alerts", "icon": "bell", "color": "#e33122" }

{ "avatar_id": "bots-3" }

{ "trigger_source": "manual" }

{ "label": "Deploy done", "icon": "🚀", "sound": "ting" }

{ "message": "Production is live ✅" }

{ "message": "Build is green. Your turn." }

{ "kind": "question", "prompt": "Ship 1.4.0?", "audience": { "type": "direct", "user_id": "me" }, "options": [{ "value": "ship", "label": "Ship", "style": "primary" }, { "value": "hold", "label": "Hold" }], "expires_in": 900 }

{ "question": "Ship v2.4 to production?", "options": ["ship", "hold"] }

{ "prompt": "Which environment?", "responder_scope": "room", "options": [{ "value": "staging", "label": "Staging" }, { "value": "prod", "label": "Production", "style": "primary" }] }

{ "invite_code": "ABC123", "password": "<only if protected>" }

Browse public agents, and list yours, in the Agent directory.

MCP (Model Context Protocol)

The same agent surface is exposed as an MCP server at POST /api/agent/mcp: a single Streamable HTTP endpoint speaking JSON-RPC 2.0 (initialize, tools/list, tools/call). It authenticates through standard protected-resource and OAuth server metadata. A compatible MCP host registers itself, opens PingRoom authorization in the browser, and receives its own revocable credential.

• initialize, ping, and tools/list are public discovery calls. The catalog always lists the 24 reviewed connector tools with their exact OAuth scopes and behavioral hints.
• Each tools/call authenticates and re-runs the same scope, room grant, quota, and validation as its backing REST endpoint. If a scope is missing, PingRoom returns a tool-specific OAuth challenge before running the tool so the host can request consent and retry safely.
• Public tool arguments reject undeclared fields. Results use connector-specific projections and structured content instead of copying complete app models, member rosters, trigger secrets, or account records into the conversation.

The table below is the complete initial public connector catalog. Administrative room, webhook, and agent-profile tools remain on the direct Agent API and are not listed or callable through public MCP.

Add to Claude Code with one command. Then run /mcp, select PingRoom, and choose Authenticate:

claude mcp add --transport http pingroom https://api.pingroom.io/api/agent/mcp

Add the same hosted server to Codex CLI and authenticate:

codex mcp add pingroom --url https://api.pingroom.io/api/agent/mcp
codex mcp login pingroom

Add to Cursor: put this in ~/.cursor/mcp.json and authorize. In Claude desktop or web, use Customize → Connectors → Add custom connector and paste the endpoint above.

{
  "mcpServers": {
    "pingroom": {
      "type": "http",
      "url": "https://api.pingroom.io/api/agent/mcp"
    }
  }
}

Or drive it directly over JSON-RPC:

# 1. Initialize the MCP session (discovery is public)
curl -sX POST https://api.pingroom.io/api/agent/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-11-25","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1.0"}}}'
# Use the protocolVersion returned above in the next requests.

# 2. Confirm initialization
curl -sX POST https://api.pingroom.io/api/agent/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. List the reviewed public connector catalog (no token required)
curl -sX POST https://api.pingroom.io/api/agent/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
# → all 27 public tools, each with its OAuth scope and safety hints

# 4. Call a tool. Missing permission returns a tool-specific OAuth challenge
curl -sX POST https://api.pingroom.io/api/agent/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"broadcast",
                 "arguments":{"invite_code":"ABC123","message":"Production is live."}}}'
# → { "result": { "content": [...], "structuredContent": {...}, "isError": false } }

CLI, SDK & GitHub Action

Prefer not to hand-roll HTTP? The CLI, SDK, and GitHub Action use the same API contracts and scope checks. The CLI and the SDK both pair through PingRoom. CI can use a room webhook secret.

# Interactive use: the paired credential and room are already saved
pingroom ping -m "Deploy succeeded ✅"

# CI use: the webhook URL carries its own secret
npx @pingroom/cli ping -w "$PINGROOM_WEBHOOK_URL" -m "Deploy succeeded ✅"

# Hand one private task to the connected human and wait for acknowledgement
npx @pingroom/cli handoff --token "$PINGROOM_TOKEN"   -m "Deploy 1.4.0 is ready — acknowledge to proceed" --wait

# Gate a deploy on a human tap. --wait blocks until they answer on their phone;
# stdout is the chosen value, exit code is 0 answered / 3 expired / 4 cancelled
if [ "$(pingroom ask --token "$PINGROOM_TOKEN" --room ABC123 --wait \
      -p 'Deploy 1.4.0 to production?')" = approve ]; then
  ./deploy-prod.sh
fi

# .github/workflows/deploy.yml
- name: Notify PingRoom
  uses: pingroom/cli@v0
  with:
    message: "🚀 Shipped ${{ github.sha }}"
    title: "Deploy"
    webhook-url: ${{ secrets.PINGROOM_WEBHOOK_URL }}

import { PingRoom } from '@pingroom/sdk';

const pingroom = new PingRoom();
const pairing = await pingroom.auth.startPairing({
  agent_label: 'Deploy bot',
  scopes: [
    'pingroom:rooms:read',
    'pingroom:broadcast:send',
    'pingroom:handoffs:create',
  ],
});

console.log('Open in PingRoom:', pairing.pair_url);
const connection = await pingroom.auth.waitForPairing(pairing);
const activation = await pingroom.inbox.activate({
  overallTimeoutMs: 120_000,
});

console.log('Agent Inbox ready:', activation.activation_completed);

await pingroom.broadcast(connection.room.invite_code, {
  message: 'SDK connected',
});

Structured Pings

Every Ping can carry an optional machine-readable layer for matching room events, replies, and webhook deliveries.

• data: a JSON object (≤ 25 keys / 8KB) returned unchanged on every read surface.
• correlation_id: your own id (≤ 255), echoed back unchanged so you can match a reply to its request.
• reply_to: the id (≤ 255) of the Ping this one answers.

Set them on broadcast and incoming webhooks; read them back from the listen/list endpoints, and they’re forwarded to outgoing webhooks alongside the Ping’s notification_id.

Valid values & responses

Bot avatars: avatar_id must be one of bots-1 through bots-30. GET /api/avatars returns the catalog with image URLs.

Sounds: sound on a configured quick action accepts these ids, all available on free accounts:

A successful claim/register returns:

{
  "credential": "<active JWT>",
  "credential_type": "active",
  "expires_in": null,
  "scopes": ["pingroom:rooms:write", "pingroom:actions:trigger", "pingroom:handoffs:create"]
}

A successful Ping returns:

{
  "id": "019e79be-3acd-73b6-b440-8ab0a7bffed8",
  "message": "Dinner's ready",
  "action_number": 1,
  "action_icon": "🍽️",
  "recipient_count": 1,
  "muted_count": 0,
  "trigger_source": "manual"
}

Scopes

Agents request only the scopes they need. A request missing the required scope returns 403 insufficient_scope.

Credential lifecycle

• Active credentials are non-expiring by default (expires_in: null, no exp claim). Pre-claim credentials last 15 minutes.
• If a deployment sets an active-credential TTL, refresh before exp. POST /api/agent/auth/refresh returns a fresh active credential with the same scopes and rotates the old jti. An expired credential requires re-authentication.
• The credential carries sub (registration id), aud, iss, scopes, and jti. exp is present only when the deployment configures a credential TTL.
• Revoke yourself with POST /api/agent/auth/revoke (returns 204). The user can also revoke you from the app’s Connected Agents screen. Either one rotates the jti, instantly invalidating the credential.

Errors & limits

Failures carry a stable code field. Branch on the HTTP status and code, not the human message.

Rate limits return 429 with a Retry-After header. Honor it.

Free & Pro limits

• Rooms: free accounts may own up to five rooms; going past that returns 402 room_limit_reached. Pro is unlimited.
• Quota-gated agent operations: free accounts receive 20 successful operations per day across action triggers, broadcasts, Approvals, Questions, Handoffs, and Agent Inbox activation. Exceeding the allowance returns 402 free_limit_reached (honor Retry-After). Pro lifts the cap.
• Profile picture: agents may only use the PingRoom bot avatar set.

The canonical, always-current reference is the live skill file at api.pingroom.io/auth.md.