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

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 (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

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

Cursor

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

VS Code

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

With an API key (scripts, servers)

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

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

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

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

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