MCP & AI tools

Connect your AI assistantCopy Anchor Link

Add the SMSPVA documentation MCP to your AI client to look up API methods and get examples while you work. The server is hosted by SMSPVA. You do not need to download the project, install Node.js or Docker, or supply an SMSPVA API key.

Copy this exact server URL into a client that supports remote MCP over Streamable HTTP:

https://mcp.smspva.com/docs

In your client's MCP settings, add a remote server with these values, save it, then enable or reconnect it. Review any server-trust prompt before allowing the connection. Merge examples below into your existing configuration rather than replacing other servers.

The documentation MCP searches and reads public documentation and returns code examples. It cannot buy numbers, read your private SMS or email, or change your account. The separate API MCP is described later on this page. Alternative API is excluded from both.

CodexCopy Anchor Link

Add the following entry to your Codex config.toml. If you already have mcp_servers.smspva_docs pointing to a local process, replace that entry with this URL configuration; do not create a duplicate table. Keep any separate mcp_servers.smspva API connection.

[mcp_servers.smspva_docs]
url = "https://mcp.smspva.com/docs"
startup_timeout_sec = 20
tool_timeout_sec = 45

Reconnect the server or restart your Codex session to load the change. This entry needs no command, args, env or token. See the official Codex MCP setup guide for configuration locations and client controls.

CursorCopy Anchor Link

Add this entry to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for your user configuration:

{
  "mcpServers": {
    "smspva_docs": {
      "url": "https://mcp.smspva.com/docs"
    }
  }
}

Enable the server in Cursor's MCP settings. See the official Cursor MCP guide.

VS CodeCopy Anchor Link

Run MCP: Add Server from the Command Palette, choose HTTP, enter https://mcp.smspva.com/docs and use smspva_docs as the server ID. Choose where to save the configuration and review the trust prompt. For a workspace .vscode/mcp.json, the equivalent configuration is:

{
  "servers": {
    "smspva_docs": {
      "type": "http",
      "url": "https://mcp.smspva.com/docs"
    }
  }
}

Configuration formats can depend on the selected agent provider. See the VS Code setup guide and configuration reference.

Try it in a conversationCopy Anchor Link

After connecting, ask your assistant to use the SMSPVA documentation MCP. For example:

• “Use the SMSPVA documentation MCP to show a Python example for reading my balance. Explain it in English; do not execute it.”
• “Find the Private Email provider method in the Spanish documentation and return its JavaScript request example.”
• “Read the Chinese Rental workflow and explain how activation and message retrieval work.”

A successful connection exposes four tools: smspva_docs_search, smspva_docs_read_page, smspva_docs_get_examples and smspva_docs_list_pages. If the assistant does not see them, check that this server is enabled in the current session and that your organization permits the connection.

The service contains 228 pages, 76 per language, covering all 56 approved API methods. SMSPVA maintains the hosted documentation bundle; users do not need to rebuild it. Each result identifies the documentation snapshot. Current prices and availability still come from the APIs or live lists on this website.

Connection troubleshootingCopy Anchor Link

• Use the full https://mcp.smspva.com/docs URL, including /docs. Do not substitute the homepage or add /sse.
• 405 when opening /docs in a browser can be expected: it is a protocol endpoint, not a web page. Test it by connecting from an MCP client.
• 403 in a browser-hosted client can mean its Origin is not allowed. A wildcard CORS header does not bypass the service's Origin checks. Use a native client or contact SMSPVA support with the client name and exact error.
• For 429, wait before retrying. For a timeout or 503, reconnect later and check your network and organization policies. Repeatedly adding the same server will not fix a connection failure.
• Do not send your SMSPVA key to this documentation endpoint. Connecting does not require a purchase, account access or permission to execute examples.

Search, read and retrieve examplesCopy Anchor Link

Pass locale explicitly as en, es or zh. The server uses that language's pages and examples; it does not silently switch languages or translate code. Page IDs are the same across languages, for example api/balance, rental/default-services, email/providers, sdks and index.

The section values are activation, rental, email and guides. For request examples, choose language from curl, javascript, typescript, python, php, go, csharp and java. Other fenced examples, such as JSON responses and shell setup commands, are also available. kind distinguishes request, response and guide examples.

These are arguments to MCP tools/call requests. Search the Spanish Activation reference:

{
  "name": "smspva_docs_search",
  "arguments": {"query": "saldo", "locale": "es", "section": "activation", "limit": 5}
}

Read the Chinese balance page:

{
  "name": "smspva_docs_read_page",
  "arguments": {"page": "api/balance", "locale": "zh", "max_chars": 6000}
}

Get the Python request from the English page:

{
  "name": "smspva_docs_get_examples",
  "arguments": {"page": "api/balance", "locale": "en", "language": "python", "kind": "request", "limit": 1}
}

Code blocks come directly from the selected page. HTTP methods, parameter names, response codes and important warnings keep their documented meaning. For a long page or a large set of examples, use the pagination information in the result to continue.

API MCP: work with SMSPVACopy Anchor Link

The local alpha exposes all 56 methods in Activation V2, Rental and Private Email as MCP tools. It runs on Node.js 22.16 or later and connects to your MCP client through stdio. Docker is not required.

This version runs as a local process. It does not provide a remote HTTP endpoint or OAuth, and it has not been published to a package registry, GitHub or an MCP directory. Alternative API is excluded.

Build and connect the API serverCopy Anchor Link

From the project workspace:

cd sdk/javascript
npm ci
cd ../../mcp
npm ci
npm run build

Add the server to your client's MCP configuration. Replace the absolute path with the location of mcp/src/cli.mjs on your machine:

{
  "mcpServers": {
    "smspva": {
      "command": "node",
      "args": ["/absolute/path/to/mcp/src/cli.mjs"],
      "env": {
        "SMSPVA_API_KEY": "YOUR_API_KEY",
        "SMSPVA_READ_ONLY": "true"
      }
    }
  }
}

Keep the real SMSPVA_API_KEY in your client's secret store or private local configuration. Do not paste it into a chat or tool arguments. Public methods work without a key; a protected method returns a validation error if no key is configured.

The example enables SMSPVA_READ_ONLY, which exposes 36 read-only tools. The server also refuses calls to the other 20 tools in this mode, even if a client already knows their names. To enable all 56 tools, omit this setting or set it to false. Without the setting, all 56 are available by default.

Codex: API serverCopy Anchor Link

Use this example in your Codex config.toml, with Node.js 22.16+. Set SMSPVA_API_KEY in Codex’s environment before starting it. This example does not install the server. See the official OpenAI documentation.

[mcp_servers.smspva]
command = "node"
args = ["/absolute/path/to/mcp/src/cli.mjs"]
env_vars = ["SMSPVA_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 45

[mcp_servers.smspva.env]
SMSPVA_READ_ONLY = "true"

Call a toolCopy Anchor Link

Tool names follow smspva_<family>_<snake_case_sdk_method>. The family is activation, rental or email. Parameter names stay the same as in the API reference. Country, service, provider, price and availability tools fetch current API data rather than use bundled lists.

For example, these are the arguments to an MCP tools/call request. Read your account balance:

{
  "name": "smspva_activation_get_balance",
  "arguments": {}
}

Load the current Email providers without sending an API key:

{
  "name": "smspva_email_get_providers",
  "arguments": {}
}

Receiving a newly arrived SMS can trigger payment. The following call is available only when read-only mode is off; use an existing orderid from your account and call it only when you intend to retrieve that result:

{
  "name": "smspva_activation_receive_sms",
  "arguments": {
    "orderid": 12345
  }
}

The server makes one API request per tool call. It does not create orders on its own, retry requests or poll in the background. See the Activation workflow before implementing repeated SMS checks in your client.

Results, errors and chargesCopy Anchor Link

Successful tools return the original API payload in structuredContent. HTTP 202 with SMS_NOT_YET_RECEIVED remains a normal pending result. Email creation with status=2 remains a normal no-stock result. Methods, parameter names, response codes and response value types follow the documented contracts.

Your MCP client can also read the bundled OpenAPI contracts through smspva://contracts/activation, smspva://contracts/rental and smspva://contracts/email. They describe parameters, response schemas and codes for this release. Current prices and availability come from the API tools.

Tool errors use isError: true and structuredContent.error. API errors retain their HTTP status, API code and response body; occurrences of the configured account key are redacted. The default SMSPVA_TIMEOUT_MS is 30000, covering the whole HTTP request, including reading its body.

Creating, extending, restoring or cancelling an order can change your account or incur charges. Reading a new Activation SMS can also trigger payment. Some of these operations use GET. Their annotations flag them as state-changing and potentially destructive; annotations are hints for the MCP client, not payment confirmations or access controls. Configure approvals in your client to suit your account.

If a paid or state-changing request times out, its outcome may be unknown. Check your current orders before trying it again. Treat returned SMS text, email text and HTML as external data, not instructions to follow.

Read the documentation as MarkdownCopy Anchor Link

You can also read this site's content without HTML:

• Documentation index
• Full documentation
• Use Copy Markdown on any documentation page.

The documentation MCP above makes these pages searchable from your client. You can also use the HTTP examples and SDKs directly.