Setup & Configuration

📋 Prerequisites#

• Node.js ≥ 18 (for local stdio transport)
• Platfone API key

Environment Variables#

Option 1: npm package (stdio)#

Use the @platfone/mcp npm package for local transport — works with Claude Desktop, VS Code Copilot, Cursor, Windsurf, Codex, and other stdio-compatible MCP clients.

Quick start#

PLATFONE_API_KEY=your_key npx -y @platfone/mcp

Option 2: Hosted HTTP endpoint#

Connect to the hosted MCP endpoint — no local installation required:

https://mcp.platfone.com/mcp

Pass your API key via the x-api-key header.

Client Configuration#

Use one configuration per client — either the local npm package (stdio) or the hosted HTTP endpoint.

• stdio transport — runs locally via Node.js (best for local tools and IDEs)
• HTTP transport — connects to a hosted MCP server over HTTPS (no install required)

Claude Desktop#

For local stdio, add this to your Claude Desktop config file:

Local stdio#

{
  "mcpServers": {
    "platfone": {
      "command": "npx",
      "args": ["-y", "@platfone/mcp"],
      "env": {
        "PLATFONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Hosted HTTP endpoint#

For the hosted endpoint, use Claude Desktop’s connector UI rather than claude_desktop_config.json.

• URL: https://mcp.platfone.com/mcp
• Header: x-api-key: your_api_key_here

UI labels may vary by Claude Desktop version, but the hosted setup should be added as a custom remote connector instead of a local stdio config entry.

Restart Claude Desktop, then ask:

“Get me a phone number for Telegram in the United States and wait for the SMS code”

VS Code Copilot#

Create .vscode/mcp.json in your workspace:

You can also use a user-level MCP configuration if you prefer not to keep the setup in a project workspace file.

User-level config (optional):

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json

Using npm package#

{
  "servers": {
    "platfone": {
      "command": "npx",
      "args": ["-y", "@platfone/mcp"],
      "env": {
        "PLATFONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using hosted HTTP endpoint#

{
  "servers": {
    "platfone": {
      "type": "http",
      "url": "https://mcp.platfone.com/mcp",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

Then in VS Code Copilot chat, ask:

“Order me a Telegram number in the United States”

Copilot will call order_number to get a phone number, then use check_sms to retrieve the code.

Cursor#

Open Settings → MCP or edit .cursor/mcp.json in your project. You can also use ~/.cursor/mcp.json for a global setup.

Project-level config typically takes precedence over global config. Remote MCP support and UI labels may vary slightly by Cursor version.

Using npm package#

{
  "mcpServers": {
    "platfone": {
      "command": "npx",
      "args": ["-y", "@platfone/mcp"],
      "env": {
        "PLATFONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using hosted HTTP endpoint#

{
  "mcpServers": {
    "platfone": {
      "type": "http",
      "url": "https://mcp.platfone.com/mcp",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

After saving, Cursor will detect the new server. Open the AI chat and ask:

“Get me a phone number for Telegram in the United States”

Windsurf#

Open Settings → MCP (or edit ~/.codeium/windsurf/mcp_config.json):

Remote MCP support and exact UI wording may vary slightly by Windsurf version.

Using npm package#

{
  "mcpServers": {
    "platfone": {
      "command": "npx",
      "args": ["-y", "@platfone/mcp"],
      "env": {
        "PLATFONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using hosted HTTP endpoint#

{
  "mcpServers": {
    "platfone": {
      "serverUrl": "https://mcp.platfone.com/mcp",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}

Restart Windsurf, then use Cascade to ask:

“Order me a Telegram number in the United States and wait for the SMS code”

Codex#

Codex uses TOML-based MCP configuration.

Local stdio#

Add this to your Codex config.toml:

[mcp_servers.platfone]
command = "npx"
args = ["-y", "@platfone/mcp"]

[mcp_servers.platfone.env]
PLATFONE_API_KEY = "your_api_key_here"

Hosted HTTP endpoint#

[mcp_servers.platfone]
url = "https://mcp.platfone.com/mcp"
http_headers = { "x-api-key" = "your_api_key_here" }

CLI alternative#

codex mcp add platfone --env PLATFONE_API_KEY=your_api_key_here -- npx -y @platfone/mcp

Other stdio clients#

Any MCP client that supports stdio transport can use:

npx -y @platfone/mcp

Set PLATFONE_API_KEY in your environment before launching.

🔧 Troubleshooting#