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
  • A payment method on file (saved via the Dashboard). Your first number must be ordered through the Dashboard to complete 3D Secure verification. Subsequent numbers can be provisioned via the MCP server.

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 ten tools. AI agents discover and call these automatically through the MCP protocol.

ToolDescriptionKey Parameters
joltsms_list_numbersList your active phone numbers with status, service label, tags, message count, and subscription detailslimit (max 10)
joltsms_get_numberGet full details for a single number including service, tags, notes, message counts, and billing datesnumber_id (UUID or phone number)
joltsms_update_numberUpdate a number's service label, tags, or notes. Only provided fields are changed.number_id, service_name, tags, notes
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, from_filter, limit (max 10), since, cursor
joltsms_mark_readMark messages as read. Single message by ID or all messages on a number.message_id or number_id (exactly one)
joltsms_wait_for_smsPoll until an SMS arrives on a specific number. This is the primary tool for OTP verification workflows.number_id (UUID or phone number), 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 (UUID or phone number), since (ISO 8601, optional)
joltsms_billing_statusCheck all subscriptions with billing health, price, renewal dates, and auto-renew status.limit (max 10)

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. Tools that accept a number_id also accept a phone number (e.g. +17243213654 or 7243213654) in place of a UUID.

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: "+16505551234", 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

No payment method on file. Order your first number through the Dashboard to save a card with 3D Secure verification. This is a one-time step -- after that, all API and MCP provisioning will use your saved payment method automatically.

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