Developers

OsmO MCP connector

OsmO is an AI assistant that answers your phone. The OsmO connector lets an AI app (Muse, ChatGPT, Claude, Grok or any Model Context Protocol client) read the calls OsmO handled for a user and place a call on that user's behalf.

Step-by-step setup for each AI app (ChatGPT, Claude, Grok, Perplexity, Cursor, Codex and more): AI phone calls guides.

Setup

Endpoint: https://api.getosmo.app/mcp (Streamable HTTP, production).
Auth: OAuth 2.1 with PKCE (S256). Discovery: https://api.getosmo.app/.well-known/oauth-protected-resource/mcp and https://api.getosmo.app/.well-known/oauth-authorization-server.
Client registration: Dynamic Client Registration (RFC 7591) and Client ID Metadata Documents are both supported. Any HTTPS redirect URI is accepted.
Sign-in: the user signs in on OsmO's own page with their phone number and a one-time SMS code, then approves access.
Scopes: osmo.help, calls.read (read tools), calls.write (place_call).
Tokens: short-lived access tokens with rotating refresh tokens. Revoke at /mcp/oauth/revoke, or the user removes the app in OsmO (Settings → AI apps).

Who can use it

An OsmO account (iOS or Android app). Phone sign-in accepts US, Canada, UK, Australia and India numbers.
Tools run with any active OsmO subscription or trial. If the plan lapses the app stays connected and each tool returns subscription_ended with a short "renew in the OsmO app" message.
No payments are taken through the connector.

Tools

Tool	Class	What it does
`osmo_help`	Read	Describes what the connector can and cannot do. No inputs. Touches no data.
`list_recent_calls`	Read	The user's recent calls. Inputs: `limit` (1–10), optional `callType` (`inbound` \| `outbound`). Returns caller name, masked number, direction, status, one-line summary, time and duration, plus `hasMore`.
`get_call`	Read	One call by `callId` (from list_recent_calls), same fields. Only the signed-in user's calls.
`find_contact`	Read	Finds someone in the user's call history by `name`. Returns a `contactId`, a masked number and when they last spoke; several matches return `code: "ambiguous"`.
`place_call`	Sensitive write	Places a real phone call for the user; OsmO's voice assistant speaks the reason. Inputs: `reason` (required), and `contactId` (preferred) or `phoneNumber` in international form, optional `contactName`, `time`. The AI app must confirm who is called and why with the user before every call. Returns the call id and status; check progress with `get_call`.

Never returned: recordings, full transcripts, full phone numbers (masked to the last four digits), or another user's data. The connector cannot send messages or change settings.

Responses, errors and limits

Every tool returns JSON text with a code — ok on success, otherwise one of ambiguous, not_found, invalid_input, refused, dial_refused, not_allowed_number, failed or subscription_ended — with a plain message the AI app can show the user.
Missing permission: HTTP 403 with WWW-Authenticate: Bearer error="insufficient_scope" naming the scope needed.
Account not usable (deleted, banned or inactive): HTTP 403 subscription_required.
Calls: at most 5 calls to one number in any 24 hours per user. A refused call returns its reason.

Privacy and support

Data use is described in our Privacy Policy. Tool requests and results are logged for 90 days for support and safety. Questions: [email protected] · Security: [email protected].