> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revdesk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI agents to RevDesk over the Model Context Protocol.

RevDesk's remote [Model Context Protocol](https://modelcontextprotocol.io) server gives AI agents a
small, auditable tool surface for calling, SMS, phone numbers, caller IDs, and usage. It uses
Streamable HTTP and the same organization-scoped API keys and least-privilege scopes as the REST API.

**Server URL:** `https://mcp.revdesk.com/mcp`

**Discovery:** `https://mcp.revdesk.com/.well-known/mcp`

## Connect

Create an API key in **Settings → API Keys**, grant only the scopes the agent needs, then configure
your MCP client with the server URL and an `Authorization: Bearer rv_…` header.

```json theme={null}
{
  "mcpServers": {
    "revdesk": {
      "type": "http",
      "url": "https://mcp.revdesk.com/mcp",
      "headers": {
        "Authorization": "Bearer ${REVDESK_API_KEY}"
      }
    }
  }
}
```

<Warning>
  Keep API keys in your MCP client's secret or environment-variable store. Never paste a key into a prompt,
  source file, or configuration file that will be committed.
</Warning>

## Tools

| Tool                       | Action                                     | Typical scopes        |
| -------------------------- | ------------------------------------------ | --------------------- |
| `send_sms`                 | Send an SMS from an owned RevDesk number   | `sms:write`           |
| `place_call`               | Place an outbound phone call               | `calls:write`         |
| `list_calls`, `get_call`   | Read call history and details              | `calls:read`          |
| `hangup_call`              | End an in-progress call                    | `calls:write`         |
| `list_phone_numbers`       | List numbers available to the organization | `phone_numbers:read`  |
| `search_available_numbers` | Search carrier inventory                   | `phone_numbers:read`  |
| `buy_phone_number`         | Purchase a number; account billing applies | `phone_numbers:write` |
| `list_caller_ids`          | List verified caller IDs and display names | `caller_trust:read`   |
| `get_usage`                | Read current-month usage                   | `usage:read`          |

The MCP layer calls the same v1 endpoints as the [official TypeScript SDK](/api-reference/sdks).
Scope checks, rate limits, idempotency, and tenant isolation are therefore enforced consistently.

## Security and approvals

Tools that send messages, place calls, buy numbers, or hang up calls change external state or incur
cost. Your agent host should require user approval before invoking them. For read-only discovery,
use a separate key containing only the necessary `:read` scopes.

The protected-resource metadata at
`https://mcp.revdesk.com/.well-known/oauth-protected-resource` lists every supported scope and the
accepted bearer method.