MCP Connector

The SMAO MCP connector lets ChatGPT, Claude, Cursor, and other Model Context Protocol clients read and configure a SMAO organization. It is an AI-friendly adapter over the existing Public API business services: it uses the same tenant scope, validators, role permissions, plan entitlements, and response shapes.

There are no resource-specific MCP URLs. Give the client one remote connector URL; it runs MCP discovery, lists the tools available to the credential, and calls them through the same endpoint.

Connector URL: https://api.smao.ai/mcp

The transport is stateless JSON-RPC over POST /mcp. GET /mcp and DELETE /mcp are not application endpoints. OAuth-capable clients discover the authorization server through the published /.well-known/* metadata; you do not configure those URLs manually.

Connect with OAuth

OAuth is the recommended setup for interactive AI clients:

1. Add a custom or remote MCP connector and enter the connector URL above.
2. Follow the browser sign-in link. A current dashboard session can continue directly to consent; otherwise sign in first.
3. Select the organization, review the requested scopes, and approve.
4. Return to the client and let it discover the available SMAO tools.

The connector supports smao.read and smao.write. The access token is bound to the selected organization, but SMAO reloads the user's current lifecycle, membership, and role on every request. Role edits, membership removal, and account deletion therefore take effect without waiting for token expiry. Disconnect and reconnect to select a different organization.

In ChatGPT developer mode, Claude.ai, and Cursor, use their custom/remote MCP connector screen and the same URL. Exact menu labels can change; no client-specific SMAO endpoint is required.

Connect with an API key

For clients that support custom HTTP headers, create a key under Settings → API Keys → New key, choose the narrowest suitable role, and configure:

Authorization: Bearer <your API key>

Claude Code example:

claude mcp add --transport http smao https://api.smao.ai/mcp \
  --header "Authorization: Bearer <your API key>"

The key is the same organization key accepted by the Public API. It is shown once: keep it in a secret manager and never paste it into a chat prompt. Delete the key in the dashboard to revoke the connection.

Access rules

Every request must pass all applicable checks:

• The organization must have global api_access. Managed white-label and distributor-managed tenants are enforced from their subscription snapshot. The default hosted SMAO instance currently follows its open-subscription policy; custom/external billing and active Enterprise subscriptions are treated as unlimited.
• OAuth is limited by the granted read/write scopes and the user's current organization role. API keys are limited by the role selected for the key.
• Tool-specific product features still apply. For example, forwarding tools require call forwarding, prompt tools require custom prompts, webhook tools require tools, and website-chat tools require widgets.
• tools/list hides tools the credential cannot use, and every call repeats the checks. MCP exposes no delete tools.

The default Member role sees only list_calls, get_call, and get_statistics. Configuring assistants, knowledge, prompts, groups, glossary, pronunciation, forwardings, or webhook tools requires Admin or a custom role with the corresponding permissions. Reading website chats needs a role that can view Inbox conversations, such as Admin.

The connector exposes tools for assistants, voices and purchased phone numbers, prompts, knowledge, groups, glossary, pronunciation, forwardings, webhook tools, call logs, website chats, and statistics. Inputs use the same snake_case fields as the Public API reference, and unknown fields are rejected. Knowledge writes trigger asynchronous indexing; poll the returned item's sync_status instead of assuming it is immediately searchable.

Call logs are read-only. get_call returns the same call detail as the Public API, including mailbox_detection for an outbound call that was started with mailbox detection. The connector cannot start calls.

Website chats are read-only too. list_chats and get_chat return the chats from your website widget and the messages the visitor saw, as the Public API does. Visitor messages are text anyone on your website can type, so AI clients are told to treat them as information, never as instructions. Replying and taking over stay in the dashboard Inbox.

Every assistant created through the connector holds a phone number until you delete it in the dashboard, because the connector has no delete tools. To give a new assistant one of your organization's purchased numbers, pass an id from list_phone_numbers as phone_number_id; otherwise the platform assigns one.

Webhook tool credentials are write-only: SMAO stores them encrypted and never returns them. A credential you give an AI client stays in that client's conversation history, so you can enter it in the dashboard instead. Never put credentials in webhook headers: headers are stored and returned in plaintext. Changing the URL of a webhook that has a stored credential requires entering the credential again, so a credential never moves to a new URL on its own.

Troubleshooting and revocation

OAuth disconnect/revocation invalidates the grant and refresh token. API-key connections remain active until the key is deleted or the organization is blocked. See Errors & Rate Limits for response shapes and limits.