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://api2.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://api2.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 and prompt tools require custom prompts.
• tools/list hides tools the credential cannot use, and every call repeats the checks. MCP v1 exposes no delete tools.

The default Member role sees only list_calls, get_call, and get_statistics. Configuring assistants, knowledge, prompts, groups, or forwardings requires Admin or a custom role with the corresponding permissions.

The current connector exposes 21 tools for assistants, prompts, knowledge, groups, forwardings, call logs, 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.

Troubleshooting and revocation

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