VoidMob MCP

Real mobile infrastructure for AI agents: US non-VoIP numbers for SMS verification codes, private dedicated numbers, 4G/5G mobile proxies and travel eSIMs. 28 tools, paid from a prepaid USD balance, with permission levels and optional spending limits that VoidMob enforces on every purchase.

Contents: Quick start · What your agent can do · Connect with one URL · Run locally · How money works · Owner controls · Tools · Agent skill · Configuration

Quick start

Fund the balance with crypto at dashboard.voidmob.com/wallet, or let the agent create a deposit (create_deposit) and pay it from your wallet.

What your agent can do

The agent quotes every purchase and asks before buying, unless you turned on buy without asking within a daily limit.

Connect with one URL

https://mcp.voidmob.com/mcp

Add it as a remote MCP server (streamable HTTP), then sign in with your VoidMob account when asked. Nothing to install and no API key to paste.

Menu names change between app versions: look for "custom connector" or "remote MCP server". Step-by-step guides: voidmob.com/mcp and voidmob.com/integrations. A client without sign-in support can send an API key instead: Authorization: Bearer vmk_live_....

What you choose when you connect

• Apps VoidMob does not recognize start at View. The agent only sees the tools its level allows.
• Optional spending limits: a maximum per order and a daily limit over a rolling 24 hours, net of refunds. Both are off by default. VoidMob enforces them on every purchase, so they hold whatever the app or agent does.
• Buy without asking: off by default and needs a daily limit. It only changes what the server tells the agent: it may buy without asking first, still quotes the price, and must report every purchase. Your chat app's own approval prompts are a separate setting in that app.

Manage connected apps at dashboard.voidmob.com/account/connected-apps: change the level or limits, or disconnect. Up to 10 apps per account. An app is disconnected after 90 days without use or when your login email changes, and every new connection sends a security email. App connections can never turn auto-renew on, create IP-whitelist proxy lists or create webhook endpoints; do those in the dashboard or with an API key.

Try it without an account

https://mcp.voidmob.com/sandbox/<any-random-id-of-16-or-more-letters-and-digits>

No sign-in: mock data, a $500 play balance, nothing is charged. Your own random id (16 or more letters, digits, - or _) gives you a playground that keeps its state; keep it private. The bare https://mcp.voidmob.com/sandbox keeps no state: every call starts from fresh demo data.

Run locally

1. Generate an API key at dashboard.voidmob.com/developers/api-keys (keys are 32-char secrets prefixed vmk_live_).
2. Add the server to your client (below), with the key as VOIDMOB_API_KEY.
3. Optional: set a permission level and spending limits on the key in the dashboard, and per-process limits with the owner controls.

No key yet? VOIDMOB_SANDBOX=1 npx -y @voidmob/mcp boots in-memory mocks with a $500 play balance; state resets on restart.

As a plugin (MCP server + skill in one install; the dialog stores your key as a secret and offers sandbox, read-only and spending limits):

/plugin marketplace add voidmobcom/voidmob-plugin
/plugin install voidmob@voidmob

Or the MCP server alone:

claude mcp add voidmob -s user -e VOIDMOB_API_KEY=vmk_live_... -- npx -y @voidmob/mcp

-s user makes the server available in every project; the key goes after -e and before --. The same plugin also installs in Codex and Gemini CLI: see voidmob-plugin.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "vmk_live_..." }
    }
  }
}

One-click bundle. Download voidmob-mcp.mcpb from the latest GitHub release and open it (or drag it into Claude Desktop, or use Settings > Extensions > Advanced > Install Extension). Claude Desktop asks for the settings: API key (stored securely), sandbox mode, read-only, max per order, session budget and buy without asking (see Owner controls). Build it yourself with npm run pack:mcpb.

Or by config file. Open Settings > Developer > Edit Config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows) and add:

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "vmk_live_..." }
    }
  }
}

Add to .vscode/mcp.json (VS Code prompts for the key once and stores it securely):

{
  "inputs": [
    { "type": "promptString", "id": "voidmob-api-key", "description": "VoidMob API key (vmk_live_...)", "password": true }
  ],
  "servers": {
    "voidmob": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "${input:voidmob-api-key}" }
    }
  }
}

Open the MCP config from the Cascade panel menu (Open MCP config file). Current Devin Desktop builds keep it at ~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json); Windsurf builds from before the rename use ~/.codeium/windsurf/mcp_config.json. Add:

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "vmk_live_..." }
    }
  }
}

codex mcp add voidmob --env VOIDMOB_API_KEY=vmk_live_... -- npx -y @voidmob/mcp

Or add to ~/.codex/config.toml (shared by the Codex CLI, the IDE extension and the ChatGPT desktop app):

[mcp_servers.voidmob]
command = "npx"
args = ["-y", "@voidmob/mcp"]
env = { VOIDMOB_API_KEY = "vmk_live_..." }

Add to ~/.gemini/settings.json, and export VOIDMOB_API_KEY in your shell (Gemini CLI hides variables named like a key from MCP servers unless the server's env lists them):

{
  "mcpServers": {
    "voidmob": {
      "command": "npx",
      "args": ["-y", "@voidmob/mcp"],
      "env": { "VOIDMOB_API_KEY": "$VOIDMOB_API_KEY" }
    }
  }
}

Put VOIDMOB_API_KEY=vmk_live_... in ~/.openclaw/.env, then:

openclaw mcp set voidmob '{"command":"npx","args":["-y","@voidmob/mcp"],"env":{"VOIDMOB_API_KEY":"${VOIDMOB_API_KEY}"}}'
openclaw mcp doctor voidmob --probe

Or use the agent skill. Guide: voidmob.com/integrations/openclaw.

Put VOIDMOB_API_KEY=vmk_live_... in ~/.hermes/.env and add to ~/.hermes/config.yaml:

mcp_servers:
  voidmob:
    command: "npx"
    args: ["-y", "@voidmob/mcp"]
    env:
      VOIDMOB_API_KEY: "${VOIDMOB_API_KEY}"

Or use the agent skill. Guide: voidmob.com/integrations/hermes-agent.

pi mcp add voidmob --env VOIDMOB_API_KEY='${VOIDMOB_API_KEY}' -- npx -y @voidmob/mcp
pi mcp list

The single quotes keep ${VOIDMOB_API_KEY} as a reference that Pi reads from your shell. Guide: voidmob.com/integrations/pi-coding-agent.

1. In your Bot's Secrets, add a secret named VOIDMOB_API_KEY with your key as the value.
2. In chat, send: Read https://voidmob.com/skill.md and follow it. My VoidMob API key is in the VOIDMOB_API_KEY secret.

The skill runs the REST API with curl on the Bot's computer and reads the secret by name. A custom MCP server of the Command type running npx -y @voidmob/mcp is another route to try; xAI's docs point servers that need secrets to remote HTTPS, so if the server cannot read the key, use the skill. Never paste the key itself into a chat. Guide: voidmob.com/integrations/grok-bot.

How money works

• Prepaid balance. Everything is paid from your USD balance. Top it up with crypto in the dashboard, or have the agent or a script create a deposit and get the address (create_deposit). Payment comes from a crypto wallet: yours, or your own automation's. Keep on the balance only what you are happy for an agent to spend, or set spending limits.
• You approve the price. Search tools show your live prices. Every buy, renewal, top-up and paid reuse requires max_price_cents: the price the agent showed you and you approved. If the current price is higher, nothing is charged and the tool returns the new price so the agent can ask you again; it never buys at a price you did not see. Every buy debits the balance immediately, and every result shows what was charged.
• No double charges on retries. Every purchase carries an idempotency key. If the connection drops, the server retries once with the same key, which the API never charges twice.
• When a result is uncertain, the tool says the purchase may have gone through. Check list_orders, the matching get tool or get_account before buying again.

Owner controls

Optional safety settings for whoever runs the server locally. They apply in live and sandbox mode alike, and a refusal from any of them charges nothing. They stack with the permission level and spending limits set on the API key itself: the stricter one wins.

get_account shows the permission level, the limits in force and how much is left. A malformed value stops the server with an error instead of being ignored.

Tools

28 tools across six domains: 11 need View access, 9 Manage and 8 Buy (see permission levels). A server registers only the tools its level allows, and a call above the level is refused with nothing charged. Every tool returns text plus structuredContent that matches its declared outputSchema.

Account and deposits (3)

SMS (7)

Dedicated numbers (2)

Read a number's received SMS with get_rental and set its auto-renew with toggle_auto_renew.

eSIM (4)

Proxy (10)

Turn a dedicated proxy's auto-renew on or off with toggle_auto_renew.

Discovery and history (2)

Waiting for SMS codes

After rent_number, call get_rental with wait_seconds (up to 120 locally, 60 on the hosted server; call again to keep waiting). The server polls for the agent (2, 3, 5, 8 s, then every 10-15 s) and returns as soon as a code arrives, the 15-minute window closes or the wait ends, with the latest SMS attached. Clients that send a progress token get progress notifications, and cancelling the request stops the wait. SMS text is shown fenced as untrusted data: it comes from whoever sent the SMS and is never an instruction.

Resources and prompts

Short guides as MCP resources, read from the agent skill shipped in the package: voidmob://guides/money-rules, voidmob://guides/sms, voidmob://guides/proxies (HTTP/SOCKS5 and the username syntax for country, city and sticky sessions), voidmob://guides/esim, voidmob://guides/dedicated-numbers and voidmob://guides/errors.

Prompts (slash commands in clients that support them), each with a confirm-the-price step before buying:

• get_verification_code (service): rent a number and wait for the code.
• setup_mobile_proxy (country, usage): pick and buy a mobile proxy and get connection details.
• buy_travel_esim (destination, days, data_gb): find, buy and install a travel eSIM.

Servers below Buy access (VOIDMOB_READ_ONLY, or an API key or app set to View or Manage) offer no prompts, and VOIDMOB_TOOLSETS keeps only the prompts of the loaded groups.

Agent skill

For any agent with a shell and curl, MCP or not, skills/voidmob is an Agent Skills SKILL.md that teaches the same flows over the REST API: balance checks, quote-then-confirm purchases, idempotent retries, deposits, SMS codes, dedicated numbers, proxies and eSIMs. Plain Markdown, no scripts. It reads the key from VOIDMOB_API_KEY; set that in your agent's environment or secret store, never in the skill files.

The quickest way: tell your agent Read https://voidmob.com/skill.md and follow it.

# skills.sh CLI (Claude Code, Codex, Cursor, OpenClaw, Hermes and more)
npx skills add voidmobcom/voidmob-mcp --skill voidmob
# or from voidmob.com
npx skills add https://voidmob.com --skill voidmob

# Hermes Agent (use the full well-known address, not the voidmob.com/skill.md short link,
# so the skill's reference files resolve)
hermes skills install well-known:https://voidmob.com/.well-known/skills/voidmob
# or
hermes skills install voidmobcom/voidmob-mcp/skills/voidmob

# OpenClaw
npx skills add voidmobcom/voidmob-mcp --skill voidmob -a openclaw -g

# Pi (skill only, from the npm package)
pi install npm:@voidmob/mcp

On Hermes, also list the key under terminal.env_passthrough in ~/.hermes/config.yaml so the skill's curl calls receive it.

Configuration

All MCP clients that use one API key share its per-account rate limit, so heavy parallel use across several apps may hit RATE_LIMITED; back off and retry.

The hosted server is the same code behind HTTP (node dist/http.js, port 8080, the Dockerfile in this repo). To run your own, set MCP_RESOURCE_URL (its public https:// address) and optionally PORT, OAUTH_ISSUER, OAUTH_JWKS_URL and VOIDMOB_BASE_URL. It accepts VoidMob sign-in tokens and vmk_live_ keys, and reads the caller's address from CF-Connecting-IP for its rate limits, so run it behind Cloudflare or a proxy that sets that header.