# @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

```bash
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`:

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

For Claude Code:

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

Get an API key at [saperly.com/settings/keys](https://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](https://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](https://github.com/Saperly/saperly-python).

## Tool groups

The canonical tool list lives in [`manifest.json`](./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](https://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](./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](./LICENSE).

## Contact

hello@saperly.com or open an issue.