Connect AI Agents directly to
real physical non-VoIP telephony.
Equip Cursor, Claude Code, Windsurf, Copilot, and custom autonomous AI coding assistants with high-fidelity Model Context Protocol tools to provision phone lines, check carrier routing, and read OTP verification codes hands-free during development and QA testing.
What is the temphonenumber MCP Server?
The Model Context Protocol (MCP) is an open specification that enables LLMs and autonomous developer agents (like Cursor, Claude Code, VS Code Copilot, and Windsurf) to securely access external tools and data sources.
By adding temphonenumber's MCP server configuration to your AI editor, your agent can autonomously provision non-VoIP numbers, query pricing rates across 150+ countries, receive incoming SMS verification codes in real-time, and report failed activations without you having to manually leave your editor.
Zero Manual Context Switching
Tell your agent "Create a test WhatsApp account and fetch the OTP code" and watch it execute directly in your terminal.
Real Non-VoIP SIM Lines
Bypasses virtual number anti-fraud filters with genuine tier-1 cellular lines on AT&T, Verizon, and Vodafone networks.
Streamable HTTP Transport
High-speed SSE serverless streaming protocol compliant with official 2025-03-26 MCP specifications.
Server Endpoint & Authentication
The MCP server is hosted at a high-availability streaming endpoint. Authentication can be performed via custom HTTP request headers or Bearer JWT token exchange.
Connection Details
Required Auth Headers
Your public developer Client ID from the developer settings portal.
Your private developer Client Secret key.
Supported AI Clients & IDE Setup
Choose your AI coding environment below for ready-to-copy JSON configuration files and one-command CLI setup:
Cursor Integration
Configure Cursor IDE to communicate directly with remote MCP servers.
- 1Open Cursor settings and find MCP servers, or edit ~/.cursor/mcp.json directly.
- 2Under the "mcpServers" key, attach the temphonenumber server block.
- 3Insert your developer x-client-id and x-client-secret headers.
- 4Save the file and verify the green status dot appears next to temphonenumber.
- 5Ask Cursor Composer to rent a phone number or check messages.
{
"mcpServers": {
"temphonenumber": {
"type": "streamableHttp",
"url": "https://www.temphonenumber.com/api/mcp",
"headers": {
"x-client-id": "YOUR_CLIENT_ID",
"x-client-secret": "YOUR_CLIENT_SECRET",
"Mcp-Protocol-Version": "2025-03-26"
}
}
}
}Available MCP Tools Catalog
The MCP server exposes 7 core actions that allow agents to query balances, list pricing catalogs, provision phone numbers, and stream SMS messages:
Returns account credit balance, currency, and subscription status.
"Check my current account balance."
Lists available countries, carriers, and non-VoIP stock pricing.
"Find available phone numbers for Telegram in the US."
Leases a short-term or long-term non-VoIP phone number for a specified service.
"Rent a US phone number for WhatsApp verification."
Polls incoming SMS verification codes and OTP text messages.
"Check incoming SMS messages for my active rental."
Flags an invalid or non-receiving number for immediate refund.
"Flag the number +14155552671 because no code arrived."
Lists all currently active rented lines, expiration timers, and history.
"List all my active rented phone numbers."
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"status": "Ready to execute. Click Execute button on the left."
}
}AI Agent Prompt Templates
Drop these pre-tested prompt instructions into your cursor rules (.cursorrules) or project instructions to train your agent on automated telephony workflows:
Instructs the agent to fetch your live balance and list active phone lines.
Automates leasing a phone number and polling for the verification code.
Instructs the agent to flag a non-responsive number and trigger an instant refund.
Testing Server Health & Tools via cURL
You can directly invoke the MCP JSON-RPC 2.0 interface using raw cURL commands in your terminal:
curl -sS "https://www.temphonenumber.com/api/mcp" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "x-client-id: YOUR_CLIENT_ID" \
-H "x-client-secret: YOUR_CLIENT_SECRET" \
-H "Mcp-Protocol-Version: 2025-03-26" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_balance","arguments":{}}}'Troubleshooting & Common Issues
Quick diagnostic solutions for common connection and authentication edge cases:
Authentication Error (401 Unauthorized)
Ensure your x-client-id and x-client-secret headers are provided correctly in your client configuration file.
Server Connection Timeout
Verify that streamableHttp transport mode is enabled and your network firewall allows HTTPS POST requests to the MCP endpoint.
Tool Not Found (404)
Confirm that your AI client sends the Mcp-Protocol-Version: 2025-03-26 header during initialize handshake.
Frequently Asked Questions
Is there any extra cost for using the MCP server compared to the REST API?
No. The MCP server is completely free to connect and query. Standard per-number pricing rates apply only when your agent successfully purchases a phone number.
How does the agent wait for incoming SMS verification codes?
When your agent calls check_messages, the server returns immediately with received messages or instructs the agent to retry within the 15-20 minute rental session window.
What happens if an SMS OTP verification code is not delivered?
Our automatic refund guarantee immediately returns credits to your wallet balance if no SMS is received within the rental session. The agent can also explicitly call flag_number to cancel immediately.
Help us improve our developer integrations.