MCP Server

The JoltSMS MCP (Model Context Protocol) server enables AI agents to provision dedicated phone numbers, receive SMS, and extract OTP codes -- all through a standardized tool interface.

Prerequisites

  • A JoltSMS account with an API key (jolt_sk_*). Create one in Dashboard → Settings → API Keys.
  • Node.js 18 or later
  • An MCP-compatible client such as Claude Code, Claude Desktop, Cursor, or any agent framework that supports MCP

Installation

No installation required. Your MCP client runs the server automatically via npx:

npx -y @joltsms/mcp-server

The server communicates over stdio and requires the JOLTSMS_API_KEY environment variable. See the configuration section below for your MCP client setup.

Configuration

Add the JoltSMS MCP server to your client's configuration file. The server communicates over stdio and is spawned automatically by your MCP client.

Claude Code

Add this to your .mcp.json file in the project root:

{
  "mcpServers": {
    "joltsms": {
      "command": "npx",
      "args": ["-y", "@joltsms/mcp-server"],
      "env": {
        "JOLTSMS_API_KEY": "jolt_sk_your_key_here"
      }
    }
  }
}

Claude Desktop

Open Claude Desktop settings and add the same configuration block to the MCP servers section of your settings JSON file.

Environment Variables

VariableRequiredDescription
JOLTSMS_API_KEYYesYour JoltSMS API key (jolt_sk_*)
JOLTSMS_API_URLNoAPI base URL. Defaults to https://api.joltsms.com

Tool Reference

The MCP server exposes seven tools. AI agents discover and call these automatically through the MCP protocol.

ToolDescriptionKey Parameters
joltsms_list_numbersList your active phone numbers with status, message count, and subscription detailslimit (max 10)
joltsms_provision_numberRent a new dedicated real-SIM US number ($50/mo). Provisioning is async; the number may take seconds to minutes to become active.area_code (optional, 3 digits)
joltsms_release_numberCancel a number. Service continues until the billing period ends.subscription_id
joltsms_list_messagesList recent SMS messages with sender, body, parsed OTP code, and timestampsnumber_id, limit (max 10), since, cursor
joltsms_wait_for_smsPoll until an SMS arrives on a specific number. This is the primary tool for OTP verification workflows.number_id, timeout_seconds (10--300, default 120), poll_interval_seconds (3--30, default 5), from_filter
joltsms_get_latest_otpGet the most recent parsed OTP code from a number. Checks the last 10 minutes by default.number_id, since (ISO 8601, optional)
joltsms_billing_statusCheck subscription and billing health. Shows status, period dates, and cancellation state.None

All tools enforce a maximum page size of 10 results per request, consistent with API key rate limits. Use the cursor parameter on joltsms_list_messages to paginate through larger result sets.

OTP Verification Workflow

The most common use case is automated OTP verification. An AI agent provisions a number, triggers an OTP on a target website, and waits for the code to arrive.

  1. 1

    Provision a number -- call joltsms_provision_number with an optional area code. Wait for the number to become ACTIVE (check with joltsms_list_numbers).

  2. 2

    Enter the number on the target site -- use the phone number to register, verify, or log in on the platform that requires SMS verification.

  3. 3

    Wait for the SMS -- call joltsms_wait_for_sms with the number ID and a timeout (default 120 seconds). The tool polls every 5 seconds until the message arrives.

  4. 4

    Extract the OTP -- the response includes the full message body and a parsedCode field with the extracted verification code. Alternatively, call joltsms_get_latest_otp for just the code.

  5. 5

    Complete verification -- enter the code on the target website to finish the process.

Example agent conversation

Agent: I'll provision a number for your PayPal verification.

> joltsms_provision_number({ area_code: "650" })
< Number provisioning started!
  Status: PROVISIONING
  Subscription: sub_abc123

Agent: Your number is +1 (650) 555-1234. I'll enter it on PayPal
       and wait for the code.

> joltsms_wait_for_sms({ number_id: "num_abc123", timeout_seconds: 120 })
< SMS received after 8.2s (2 polls):
  From: +18005551234
  To: +16505551234
  Body: Your PayPal code is 847291

  OTP Code: 847291

Agent: The verification code is 847291. Entering it now...

Troubleshooting

"Missing required env: JOLTSMS_API_KEY"

Set the JOLTSMS_API_KEY environment variable in your MCP configuration. Generate a key from Dashboard → Settings → API Keys.

Connection refused

Verify that JOLTSMS_API_URL points to the correct API endpoint. The default is https://api.joltsms.com. If you are running the API locally, set it to http://localhost:8080.

Timeout waiting for SMS

Increase the timeout_seconds parameter (up to 300). Confirm the number is in ACTIVE status with joltsms_list_numbers. Verify the target platform actually sent the SMS -- some platforms throttle or block repeat verification attempts.

402 Payment Required

Your account needs a valid payment method. Add a card in the Dashboard → Billing section. If 3D Secure authentication is required, the tool returns a URL the user must visit to authorize the payment.

401 Unauthorized

The API key is invalid, expired, or revoked. Check that the full key (starting with jolt_sk_) is set correctly. You can verify active keys in Dashboard → Settings → API Keys.

API ReferenceWebhooks