saperly-mcp: Instructions file for Codex

AGENTS.md: @saperly/mcp

Patterns and pitfalls for AI agents (Claude Desktop, Claude Code, Cursor) using the Saperly MCP server. If you are an MCP client reading this autonomously, the tool names and patterns below are canonical — see the generated tool index at the end of this file for the full list.

1. What Saperly is

Saperly is the phone carrier for AI agents. One API call gives any agent a real phone number with TCPA compliance, consent capture, and an audit trail built in. Hosted mode runs the AI for you (Saperly handles speech-to-text, the LLM call, and text-to-speech). Webhook mode lets your backend decide responses turn by turn. Audio mode streams raw audio over a WebSocket if you need full control of the media plane.

2. Installation

For Claude Code:

claude mcp add saperly -- npx -y @saperly/mcp
export SAPERLY_API_KEY=sk_live_...

For Claude Desktop, add this entry to claude_desktop_config.json:

{
  "mcpServers": {
    "saperly": {
      "command": "npx",
      "args": ["-y", "@saperly/mcp"],
      "env": { "SAPERLY_API_KEY": "sk_live_..." }
    }
  }
}

Transport is stdio. The server is a Node.js 18+ binary published as @saperly/mcp.

3. Authentication

Saperly uses a two-tier credential model. The MCP server reads exactly one credential from the environment at startup; pick the tier that matches the tools you plan to call.

Credential	Prefix	What it does	Where to get it
API key	sk_test_… / sk_live_…	Place calls, send SMS, manage lines, query usage.	Portal, or minted by a service key via POST /v1/keys.
Service key	sk_svc_test_… / sk_svc_live_…	Mint, list, get, update, rotate, revoke child API keys. Credential management only.	Portal only (Settings → Service Keys).

Child API keys minted by a service key carry their own scope. The API accepts exactly four permission tiers on POST /v1/keys and PATCH /v1/keys/{id}. A fifth value, legacy_full, appears on responses for keys minted before v0.5.7.0 but cannot be set via the API.