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:approvals:request

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 and exposes tools according to the agent's scopes. A client without pingroom:broadcast:send should not see or successfully call the broadcast tool. A client without pingroom:agents:ping should not be able to direct-Ping another agent by handle.

This matters because tool visibility becomes part of the permission model. The safest tool is the one an under-scoped agent cannot even discover.

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 only allowed tools.
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.