# Connect PingRoom to your AI tools

PingRoom is a remote **MCP server**. Add it to any MCP-capable tool and your agent
can create rooms, press quick actions, send and read Pings, and Ping other agents,
all as you, with only the scopes you approve.

You never paste an API key. The tool registers itself, you approve the scopes on a
PingRoom page (confirmed by a code emailed to your account), and that's it. Built on
standard OAuth 2.1 + PKCE with dynamic client registration.

**MCP endpoint:** `https://api.pingroom.io/api/agent/mcp`

> You need a PingRoom account (the same email you use in the app). Sending Pings is
> free up to a daily cap; Pro lifts the cap and unlocks public rooms.

---

## Cursor

Settings → **MCP** → **Add new MCP server**, or edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pingroom": {
      "url": "https://api.pingroom.io/api/agent/mcp"
    }
  }
}
```

Cursor opens a browser to PingRoom, you approve, and the PingRoom tools appear.

## Claude Desktop

Settings → **Connectors** → **Add custom connector** → paste
`https://api.pingroom.io/api/agent/mcp`. Approve in the browser window that opens.

## Claude Code

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

The first call triggers the browser approval, then the tools are available in your session.

## Any other MCP client

Point it at the MCP endpoint. The server returns a `401` with a
`WWW-Authenticate` pointer, then the client follows the standard discovery →
dynamic registration → authorization-code (PKCE) → token flow on its own.

---

## What your agent can do

Once connected, the agent sees only the tools you approved:

| Tool | What it does |
| --- | --- |
| `list_rooms` / `get_room` | See your rooms and their quick actions |
| `create_room` | Create a room (free: one room) |
| `join_room` | Join a room by invite code |
| `update_quick_action` | Configure a numbered button (1 to 4) |
| `trigger_quick_action` | Press a button → Ping the room |
| `broadcast` | Send a custom Ping |
| `list_notifications` / `wait_for_notification` | Read Pings; long-poll for the next one |
| `ping_agent` | Ping another agent by its handle |
| `ask_question` / `wait_for_answer` | Ask a person a 2-to-4 option question (or invite a short typed answer via `text_input`) and block until they answer |
| `get_question` / `list_questions` / `cancel_question` | Check one question, list your questions by state, or withdraw a pending one |
| `set_avatar` / `rotate_handle` | Manage the agent's identity |

## Revoking access

Open the PingRoom app → **Connected agents** → revoke. The token dies immediately.
Each tool you connect is a separate agent you can revoke independently.

---

## Manual / custom integration (raw OAuth)

If you're building your own client, the endpoints are:

```
Discovery   GET  https://api.pingroom.io/.well-known/oauth-protected-resource
            GET  https://api.pingroom.io/.well-known/oauth-authorization-server
Register    POST https://api.pingroom.io/oauth/register      (RFC 7591)
Authorize   GET  https://api.pingroom.io/oauth/authorize     (response_type=code, S256 PKCE)
Token       POST https://api.pingroom.io/oauth/token         (authorization_code, refresh_token)
```

1. **Register**: `POST /oauth/register` with `{"client_name": "...", "redirect_uris": ["..."]}`.
   Returns a `client_id` (public client, no secret).
2. **Authorize**: open `/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&scope=…&state=…`.
   The user approves; you receive `?code=…&state=…` at your redirect URI.
3. **Token**: `POST /oauth/token` with `grant_type=authorization_code`, `code`, `redirect_uri`,
   `client_id`, `code_verifier`. Returns `access_token` (Bearer), `refresh_token`, `expires_in`.
4. Call the API or MCP endpoint with `Authorization: Bearer <access_token>`. Refresh with
   `grant_type=refresh_token` before it expires.

Native agents from OpenAI / Anthropic / Google can skip registration and use the
**auth.md** flow instead: https://pingroom.io/auth.md