@saperly/mcp

Model Context Protocol server for Saperly. Gives any MCP-compatible AI agent (Claude Desktop, Claude Code, Cursor) the ability to provision phone numbers, place calls, send SMS, and manage credentials.

32 tools across 12 groups, all backed by the public Saperly API.

Install

npm install -g @saperly/mcp

Or run on demand with npx @saperly/mcp.

Quickstart

Register the server with Claude Desktop. Add this block to claude_desktop_config.json:

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

For Claude Code:

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

Get an API key at saperly.com/settings/keys. For key-management tools (saperly_key_*) set SAPERLY_API_KEY to a service key instead.

Use as a hosted connector

Same auth model, no local install — the hosted connector serves the OAuth-usable surface (the service-key saperly_key_* tools stay local-only). The hosted endpoint at https://saperly.com/api/v1/mcp speaks the streamable HTTP transport and accepts three credential types: API-key bearer, opaque connector URL, and OAuth 2.1 access token (Saperly is the issuer).

• Anthropic Messages API (mcp_servers): point at https://saperly.com/api/v1/mcp and pass your API key as authorization_token.
• Claude.ai custom connector — OAuth tab: paste https://saperly.com/api/v1/mcp. Claude does the discovery + dynamic registration + PKCE dance and lands the user on a consent screen at saperly.com.
• Claude.ai custom connector — No auth tab: mint a connector URL at saperly.com/settings/connectors and paste it with auth set to None.
• ChatGPT — custom connector: add https://saperly.com/api/v1/mcp; ChatGPT runs the same OAuth discovery + registration flow as Claude.ai.
• CrewAI: pip install "saperly[crewai]" then wrap with SaperlyTools(api_key=…). See the Python SDK.

Tool groups

The canonical tool list lives in manifest.json. One sentence per group:

• lines: Provision and manage phone numbers (modes: webhook, audio, hosted).
• calls: Start and control calls, wait for inbound calls, retrieve history, run hosted AI conversation calls.
• messages: Send outbound SMS and read inbound conversation history.
• keys: Mint, rotate, and revoke child API keys (service-key auth required).
• consent: Grant, check, and revoke TCPA outbound consent per phone number.
• disclosures: Configure TCPA disclosure scripts played at call start.
• billing: Read account balance and transactions.
• account: Whole-account snapshot covering lines, balance, usage, and recent calls.
• webhooks: List delivery attempts, read aggregate stats, send test webhooks.
• usage: Aggregate call minutes, SMS counts, and costs by day or month.
• settings: Read or update account-level configuration (e.g. default webhook URL).
• voices: List TTS voices available for hosted-mode calls.

Auth

Saperly uses a two-tier credential model. Both authenticate via SAPERLY_API_KEY on the MCP server's environment.

Credential	Use case
API key (sk_live_…, sk_test_…)	Place calls, send SMS, manage lines, read usage.
Service key (sk_svc_live_…, sk_svc_test_…)	Mint, rotate, and revoke child API keys via the saperly_key_* tools. Credential management only.

Full reference at docs.saperly.com/service-keys.

Resources

• Docs: https://docs.saperly.com
• Quickstart: https://docs.saperly.com/quickstart
• Agent onboarding: https://docs.saperly.com/agent-onboarding
• Service keys: https://docs.saperly.com/service-keys
• Patterns and pitfalls: ./AGENTS.md
• API reference: https://docs.saperly.com/api-reference
• Issues: https://github.com/Saperly/saperly-mcp/issues
• Discord: invite link in our docs

License

MIT. See LICENSE.

Contact

hello@saperly.com or open an issue.