# Saperly Mcp

> MCP server for Saperly — give any AI agent a phone number

- **Type:** MCP server
- **Install:** `agentstack add mcp-saperly-saperly-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Saperly](https://agentstack.voostack.com/s/saperly)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Saperly](https://github.com/Saperly)
- **Source:** https://github.com/Saperly/saperly-mcp

## Install

```sh
agentstack add mcp-saperly-saperly-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Saperly](https://github.com/Saperly)
- **Source:** [Saperly/saperly-mcp](https://github.com/Saperly/saperly-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-saperly-saperly-mcp
- Seller: https://agentstack.voostack.com/s/saperly
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.