# AI agents (MCP)

An MCP (Model Context Protocol) server so your AI assistant can send SMS, check deliveries, manage contacts and Verify codes in your account. Server URL:

```
https://app.ogave.co/mcp
```

## Connect {#connect}

Recommended: add the URL in your AI app and sign in when it asks (OAuth). A screen lets you choose test or live mode and the permissions. Disconnect it any time in Developers › API keys › Connected AI apps. Team members can only give the permissions of their role.

### Claude {#claude}

Claude (web and desktop): Settings › Connectors › Add custom connector › the URL above. Claude Code:

```
claude mcp add --transport http ogave-sms https://app.ogave.co/mcp
```

### ChatGPT {#chatgpt}

Settings › Connectors (developer mode) › Create › MCP server URL = the one above, authentication OAuth.

### Cursor {#cursor}

```
// ~/.cursor/mcp.json
{ "mcpServers": { "ogave-sms": { "url": "https://app.ogave.co/mcp" } } }
```

### VS Code {#vscode}

```
// .vscode/mcp.json
{ "servers": { "ogave-sms": { "type": "http", "url": "https://app.ogave.co/mcp" } } }
```

### With an API key (scripts, servers) {#api-key}

Create a key in Developers › API keys with the mcp permission (plus the ones the tools need) and send it as a header:

```
Authorization: Bearer test_…
// Cursor / VS Code: "headers": { "Authorization": "Bearer ${env:API_KEY}" }
```

With a test_ key everything is simulated: nothing is sent or charged.

## Tools {#tools}

| Tool | What it does | Permission |
| --- | --- | --- |
| `quote_price` | Price, segments and encoding of one SMS before sending it. Nothing is sent. | `balance:read` |
| `send_sms` | Send one SMS. Without confirm: true it only returns the quote; show it to the user and ask before confirming. | `messages:send` |
| `send_batch` | Send one text to a contact list or to up to 10,000 numbers per call. dry_run (default true) returns recipients, segments and total cost; send with dry_run: false after the user agrees. | `messages:send` |
| `get_message` | Status, receipt, price and error of one message. | `messages:read` |
| `list_messages` | Newest first, with filters. | `messages:read` |
| `get_balance` | Balance and currency of the account. | `balance:read` |
| `list_contact_lists` | Contact lists with their ids and sizes. | `contacts:read` |
| `add_contacts` | Add or update up to 100 contacts in a list. Without confirm: true it only validates. | `contacts:write` |
| `verify_start` | Send a Verify one-time code at once (no confirmation needed): by SMS to a phone number, by email to an address (channel email), or SMS first and the code by email if it is not verified in time (channel auto, give email). | `verify` |
| `verify_check` | Check the code the person received. | `verify` |
| `get_report` | Messages, delivery rate and cost for a period, grouped. | `reports:read` |
| `send_email` | Send a transactional email to one address or up to 10,000 (one email each) from a sending identity of the account (see list_email_identities). Assistant mode: without confirm: true it only returns the price; show it to the user and ask before confirming. | `email:send` |
| `get_email` | One email with its delivery timeline (accepted, sent, delivered, bounced, opened, clicked…). | `email:read` |
| `list_emails` | Newest first, each with its timeline. Filters: status, to, tag. | `email:read` |
| `list_email_identities` | The sending domains and addresses the account may send email from. | `email:read` |
| `list_sender_ids` | Sender IDs approved on the account. | `messages:read` |
| `list_templates` | Approved SMS templates (id, name, text with {placeholders}). | `messages:read` |

Resources: the API documentation (docs://api), this guide (docs://mcp) and prices per country (pricing://countries). Prompts: "write and send a campaign", "check delivery of the last campaign".

## Modes: assistant or automatic {#modes}

Every API key or connected app has a mode (Developers › API keys › AI agent):

- **Assistant** (default): for people using an AI app by hand. send_sms, send_email and add_contacts only act with confirm: true; without it they return the price or what they would do. send_batch is a dry run unless dry_run: false. The server instructions tell the agent to ask first.
- **Automatic**: for automating tasks. send_sms, send_batch, send_email and add_contacts act on the first call, within the key's limits: max spend per day (required), recipients per call, and optionally the allowed sender IDs, email senders, templates and hours. A send over a limit returns a clear error and nothing is sent (never a partial send). Revoking the key stops it at once.
- verify_start (by SMS, email or auto) never needs a confirmation: one recipient, asked by the app, protected by Verify's fraud limits.

## Limits {#safety}

- At most 10,000 recipients per call (safety limit, send_email too); for more, use portal campaigns.
- The account may raise it up to 100,000 in Developers › API keys › AI agents, by explicitly accepting that an AI agent may make mistakes (wrong list, wrong text) and that sends above 10,000 recipients are its own responsibility; a send_batch result above 10,000 carries a warning. Lowering it needs nothing.
- Email: send_email sends one email per address from a sending identity of the account (list_email_identities); get_email and list_emails return the timeline (delivered, bounced, opened…). Scopes email:send / email:read.
- Same rate limits as your API key; every send (and every send refused in automatic mode) is in the activity log (Account › Team › Activity).

## Docs for AI tools {#llms}

To let an assistant read these docs without the HTML: [`https://app.ogave.co/llms.txt`](https://app.ogave.co/llms.txt) (index), [`/llms-full.txt`](https://app.ogave.co/llms-full.txt) (every page in one file) and each page as Markdown by adding `.md` to its address, e.g. [`/docs/api.md`](https://app.ogave.co/docs/api.md).