NAV
code
  • SMSAPI MCP Server (Model Context Protocol)
  • 1. Architecture
  • 2. Prerequisites
  • 3. Authorization and Permissions (Scopes)
  • 4. Server Configuration
  • 5. Available Endpoints and Tools
  • 6. Example Use Cases (Prompts)
  • 7. Troubleshooting

    • SMSAPI MCP Server (Model Context Protocol)

    Connect AI agents and LLMs directly to SMS communication.

    SMSAPI MCP Server is an implementation of the open Model Context Protocol standard that enables AI models such as Claude, GPT, and autonomous agents to directly use SMSAPI platform features. With this integration, AI can not only analyze data but also send notifications, check delivery statuses, and manage the contacts database on your behalf.

    1. Architecture

    The integration is based on a standardized communication model where the MCP server acts as a translation layer between AI intent and specific REST API calls.

    Communication flow:

    AI Agent e.g. Claude <-> MCP Client <-> SMSAPI MCP Server <-> SMSAPI API

    2. Prerequisites

    Before you start, make sure you have:

    3. Authorization and Permissions (Scopes)

    The MCP server supports two authorization methods:

    1. OAuth 2.0 webflow (recommended) — the MCP client automatically performs authorization via a browser. The user logs in to SMSAPI and grants access to selected scopes. The token is refreshed automatically. Configuration only requires providing the server URL without an Authorization header.
    2. Static OAuth2 token — manually generated token in the SMSAPI Customer Panel (API Settings -> OAuth Tokens), provided in the Authorization: Bearer header.
    Feature Required Permission (Scope)
    SMS sms
    Contacts contacts
    Account/Balance profile
    Subusers subuser
    Short URL (cut.li) short_url
    HLR hlr
    Blacklist blacklist
    Sender Names sms_sender
    MFA mfa
    Callbacks callbacks

    4. Server Configuration

    SMSAPI MCP Server is available at https://mcp.smsapi.io/ and uses Streamable HTTP transport.

    Claude Desktop

    
{
  "mcpServers": {
    "smsapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.smsapi.io/",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <PASTE ACCESS TOKEN HERE>"
      }
    }
  }
}

    Open the claude_desktop_config.json file and add the server in the mcpServers section:

    Cursor

    1. Go to Settings -> MCP.
    2. Click Add new global MCP server.
    3. Paste the JSON configuration above. Cursor will automatically detect available tools (indicated by a green marker).

    Claude Code (CLI)

    
claude mcp add smsapi \
  --transport http \
  https://mcp.smsapi.io/ \
  --header "Authorization: Bearer YOUR_OAUTH2_TOKEN"

    Add the server directly from the terminal:

    5. Available Endpoints and Tools

    You can limit the AI agent's access to specific tool groups by changing the endpoint URL in the configuration.

    Group Endpoint Description
    All / Full access to all available tools.
    SMS /sms Sending (single/group), scheduling, statuses, removing scheduled.
    Contacts /contacts Contact management, groups, contact group lookup, custom fields.
    Account /account Balance check, sender name management.
    Subusers /subusers Subuser management: create, edit (including point limits and activation/deactivation), delete.
    Short URL /short-url Generating cut.li links and click statistics.
    HLR /hlr Number validation (HLR lookup).
    Blacklist /blacklist Blacklist management: add (with optional expiration date), remove, clear all, CSV import.

    6. Example Use Cases (Prompts)

    Once the server is connected, you can issue commands in natural language:

    7. Troubleshooting

    Error Cause Solution
    401 Unauthorized Invalid or expired token. Generate a new token in the Customer Panel.
    403 Forbidden Token lacks required scopes. Check the permissions table in section 3.
    Tools not visible MCP client configuration error. Check URL and Authorization header. Restart the application e.g. Claude Desktop.
    Timeout Network or HTTP transport issues. Make sure your client supports Streamable HTTP transport.

    Want to learn more about the protocol?

    Visit the official website at modelcontextprotocol.io.

    code