Ping MCP Server

Let AI agents (Claude Code, Cursor, Codex) notify your phone and request lock-screen approvals — no webhook scripting.

Setup (step by step)

1. Create an API key

In the Ping dashboard go to Settings → API Keys → Create Key. Give the key a descriptive name (e.g. "Claude Code" or "Cursor").

The full key (pk_live_…) is shown once — copy it and store it somewhere safe before closing the dialog. See API Keys for details.

2. Register the server with your client

Claude Code (CLI):

claude mcp add --transport http ping https://ping-api-production.up.railway.app/mcp \
  --header "Authorization: Bearer pk_live_…"

Cursor / Claude Desktop (mcp.json):

{
  "mcpServers": {
    "ping": {
      "url": "https://ping-api-production.up.railway.app/mcp",
      "headers": { "Authorization": "Bearer pk_live_…" }
    }
  }
}

3. Verify the connection

Restart your client and approve the ping server when prompted. Then confirm the five tools are available — in Claude Code you can call:

If it returns a list of your channels, you're connected.

Tools

• ping_list_channels() → { channels: [{ id, name }] }
• ping_send(channel?, title, body?, priority?) → { message_id }. channel is a name or id; omit for your default (oldest) channel.
• ping_request_approval(channel?, title, body?, ttl_ms?) → { approval_id, expires_at }. Buttons are always Approve/Reject (iOS can't render custom-label lock-screen buttons) — phrase the decision in the title/body.
• ping_check_approval(approval_id, max_wait_ms?) → one of {status:"approved",value} | {status:"rejected"} | {status:"pending"} | {status:"expired"}. Bounded ≤50s; on pending, call again. Idempotent. Default on expiry = deny.
• ping_cancel_approval(approval_id) → {status:"cancelled"} | {status:"already_resolved"}.

Use it from the Ping monorepo (project MCP)

The repo's .mcp.json already registers a ping server, so Claude Code (and any project-scoped MCP client) picks it up automatically. It reads two environment variables so no key is committed:

• PING_API_KEY — your pk_live_… key (required). Export it in your shell or add it to .claude/settings.local.json's env block (gitignored). Without it the server shows as unavailable.
• PING_MCP_URL — endpoint override. Defaults to the production URL (https://ping-api-production.up.railway.app/mcp). To dogfood your local branch, run the API (cd ping-api && npm run dev) and set PING_MCP_URL=http://localhost:3000/mcp.

export PING_API_KEY=pk_live_…
# optional, for local-branch testing:
export PING_MCP_URL=http://localhost:3000/mcp

Restart Claude Code, approve the ping server when prompted, and the five ping_* tools become callable in-session.

Security & best practices

• Treat the key like a password. Anyone with it can send notifications and trigger approvals on your account.
• Store it in an environment variable, not in a committed config file. Use your shell profile, a .env file (gitignored), or your client's secrets store.
• One key per client. Create a separate key for Claude Code, Cursor, CI, etc. so you can revoke one without affecting the others.
• Revoke keys you no longer use. If a key is compromised or a client is decommissioned, delete it immediately in Settings → API Keys.
• All tool calls are scoped to your account. The key grants access only to your channels — there is no cross-account access.