Connecting An MCP Client To PingRoom

MCP is the tool surface for agents. OAuth is the connection surface for humans approving access.

For PingRoom, the two belong together. A client should be able to discover PingRoom, register or identify itself, request scopes, receive user consent, and then call the MCP endpoint with an agent credential. The user should be able to see and revoke the connected agent later.

The practical goal is five-minute adoption: paste a PingRoom MCP URL into a capable client, approve the scopes, and send the first phone Ping.

Discovery First

An MCP client starts by discovering metadata.

The public web routes include OAuth and protected-resource metadata:

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
GET /auth.md

Those documents tell the client which authorization endpoint, token endpoint, scopes, and resource identifiers to use. They also make PingRoom easier for agents to understand without a human copying instructions line by line.

Dynamic Client Registration

Generic MCP clients often need dynamic client registration.

PingRoom's OAuth lane includes:

POST /oauth/register
GET  /oauth/authorize
POST /oauth/token

The client registers redirect URIs and metadata, starts an authorization request with PKCE, and exchanges the resulting code for an agent credential. The credential is not a broad user token. It is an agent-scoped credential bound to a registration and limited by the scopes the user approved.

Scope Selection

Scope selection should be honest and narrow.

An MCP client that only needs to send deploy Pings might request:

pingroom:rooms:read pingroom:broadcast:send pingroom:notifications:read

A client that configures room buttons might add:

pingroom:actions:write pingroom:actions:trigger

A client that handles human gates needs:

pingroom:questions:ask

The client should explain why it needs each permission. That makes the consent screen meaningful instead of ceremonial.

Calling The MCP Endpoint

After authorization, the client calls PingRoom's MCP endpoint:

POST /api/agent/mcp
Authorization: Bearer AGENT_TOKEN
Content-Type: application/json

The endpoint speaks JSON-RPC. tools/list returns the same reviewed public catalog for every connection; each tool call checks its required scope. A client without pingroom:broadcast:send cannot successfully call broadcast and may need to request authorization.

Direct agent Pings by handle and the ping_agent tool are retired. The legacy pingroom:agents:ping scope grants nothing. Agents collaborate by joining a shared room and broadcasting there.

Same Backing Rules

The clean implementation pattern is to route MCP tools back through the same application behavior as REST.

If a tool triggers a room action, it should re-enter the same route behavior that validates action number, room access, quota, member permissions, and payload shape. If a tool requests an approval, it should use the same approval service and wait endpoint the REST path uses.

That prevents drift. The MCP layer stays a protocol adapter, not a parallel product.

What A Good First Test Looks Like

A successful first connection should prove four things:

1. The client discovers PingRoom metadata.
2. The user consents to specific scopes.
3. The MCP client lists the public catalog and verifies that its granted scopes allow the intended call.
4. A tool call sends a real push to a phone.

That last step is critical. The agent platform is only convincing when the loop reaches a human device. MCP gives the agent a tool, but PingRoom's value is that the tool becomes a real signal.