"Find eSIM data packages for Turkey and buy the cheapest 5GB option"

Quick Start

Three steps: install → add your TCXC credentials → connect your AI client.

1. Install

Requires Python 3.10+ and a TelecomsXChange (TCXC) or NeuTRAFIX (NTX) account.

# Clone and navigate
git clone https://github.com/TelecomsXChangeAPi/tcxc-mcp-server.git
cd tcxc-mcp-server

# Setup virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create your config from the template
cp .env.example .env

2. Add Your TCXC Credentials

Get your API credentials from your dashboard:

• TCXC: members.telecomsxchange.com → Account → API Settings
• NeuTRAFIX: members.neutrafix.net → Account → API Settings

Edit .env:

# Buyer credentials (required)
TCXC_USERNAME=your_username
TCXC_API_KEY=your_api_key

# Seller credentials (required)
TCXC_SELLER_USERNAME=your_seller_username
TCXC_SELLER_API_KEY=your_seller_api_key

# API endpoint
# NeuTRAFIX users: change the base URL to https://apiv2.neutrafix.net
TCXC_API_BASE_URL=https://apiv2.telecomsxchange.com

Both buyer and seller credentials must be provided for the server to start.

3. Connect Your AI Client

The server speaks standard MCP over stdio and works with every major MCP client:

In every case, use absolute paths and restart the client after changing its config.

Claude Desktop

Add to the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "tcxc": {
      "command": "/absolute/path/to/tcxc-mcp-server/start_mcp_server.sh"
    }
  }
}

Claude Code (CLI)

claude mcp add tcxc /absolute/path/to/tcxc-mcp-server/start_mcp_server.sh

OpenAI Codex CLI

codex mcp add tcxc /absolute/path/to/tcxc-mcp-server/start_mcp_server.sh

Or add to ~/.codex/config.toml:

[mcp_servers.tcxc]
command = "/absolute/path/to/tcxc-mcp-server/start_mcp_server.sh"

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "tcxc": {
      "command": "/absolute/path/to/tcxc-mcp-server/start_mcp_server.sh"
    }
  }
}

Any Other MCP Client

Point your client at the wrapper script (which loads credentials from .env):

command: /absolute/path/to/tcxc-mcp-server/start_mcp_server.sh

Or run the Python entry point directly and pass credentials as environment variables:

command: /absolute/path/to/tcxc-mcp-server/venv/bin/python
args:    ["/absolute/path/to/tcxc-mcp-server/src/tcxc_mcp/server.py"]
env:     TCXC_USERNAME, TCXC_API_KEY, TCXC_SELLER_USERNAME, TCXC_SELLER_API_KEY

Running Standalone

# Activate environment
source venv/bin/activate

# Start server
./start_mcp_server.sh

# Or run directly
python src/tcxc_mcp/server.py

Testing

Use the interactive client to test tools:

source venv/bin/activate
python src/tcxc_mcp/mcp_client.py

Interactive commands:

• list_tools - Show all available tools
• call_tool <name> <json_params> - Execute a tool
• list_prompts - Show guided workflows
• get_prompt <name> <json_args> - Get workflow guidance

Available Tools

Voice Operations

search_voice_market(prefix="1", route_type="CLI")
get_voice_destinations(country="United States")
list_call_records(date_from="2026-01-01", date_to="2026-01-31")
test_voice_route(i_account="123", cld1="+12125551234", cli1="+12025551234", i_connection1="8721", ...)

SMS Operations

marketview_search_sms(prefix="44", country="United Kingdom")
buyers_smshistory(date_from="2026-01-01", date_to="2026-01-31")
buyers_sms_summary(date_from="2026-01-01", date_to="2026-01-31")

DID Management

number_market(country="United States", did_type="mobile")
number_list(prefix="1")
number_purchase(i_did="12345", billing_i_account="123", contact="sip:user@domain.com")

eSIM Exchange

esim_countries()
esim_market(country="Turkey")
esim_purchase(i_esim_package="456", i_account="123")
esim_list()
esim_topup_list(iccid="8944500000000000000")
esim_topup_purchase(iccid="8944500000000000000", package_type_id="789", i_account="123")
esim_orders(date_from="2026-01-01", date_to="2026-01-31")

Financial & Account

buyers_balance()
seller_balance()
buyers_payhistory(date_from="2026-01-01", date_to="2026-01-31")
buyers_account_list()

Utilities

hlr_lookup(number="+12125551234", i_account="123")
get_number_score(phone_number="+12125551234")
tools_country_codes()

Full tool list: 55 tools available. See tool documentation for details.

Guided Workflows (Prompts)

The server includes intelligent prompts for complex tasks:

• search_best_voice_rates - Find and compare voice carriers
• monitor_account_health - Comprehensive account health check
• purchase_did_workflow - Guided DID purchase process
• analyze_call_quality - CDR analysis and quality insights
• sms_market_research - SMS carrier comparison
• validate_routing_setup - Test and validate phone routing
• compare_carriers - Head-to-head carrier comparison

Use prompts in Claude: "Use the monitor_account_health prompt to check my TCXC account"

See PROMPTS.md for the full guide.

Troubleshooting

Server won't start

# Check environment variables
cat .env

Confirm all four credential variables are set (buyer and seller).

Authentication fails

# Test credentials directly
curl -u "$TCXC_USERNAME:$TCXC_API_KEY" \
     --digest \
     "$TCXC_API_BASE_URL/buyers/balance"

Import errors

# Reinstall dependencies
pip install -r requirements.txt

# For HTTP/2 support
pip install "httpx[http2]"

Claude Desktop connection issues

• Use absolute paths (no ~ or relative paths)
• Restart Claude Desktop after config changes
• Check Claude logs: tail -f ~/.config/claude/mcp.log

Development

# Install dev dependencies
pip install -e ".[dev]"

# Format code
make format

# Run linting
make lint

# Type checking
make typecheck

# Run tests
make test

Architecture

• Framework: FastMCP (official MCP Python SDK)
• HTTP Client: HTTPX with HTTP/2 and digest auth
• Authentication: Dual account support (buyer/seller)
• Security: Input validation, TLS 1.2+, rate limiting
• Performance: Async/await, connection pooling

Security

• Credentials stored in .env (never committed to git)
• File permissions: chmod 600 .env and chmod 700 start_mcp_server.sh
• All inputs validated and sanitized before API calls
• TLS verification enforced (TLS 1.2+)
• Error messages sanitized to prevent information disclosure

See SECURITY.md for detailed security practices.

Environment Support

Production: https://apiv2.telecomsxchange.com

• Real billing and provisioning
• Use production credentials

Sandbox: Contact TCXC support for sandbox endpoint

• Safe testing environment
• No real billing impact

Frequently Asked Questions

What is the TCXC MCP Server?

The TCXC MCP Server is an open-source Python implementation of the Model Context Protocol that gives AI assistants direct, secure access to the TelecomsXChange wholesale telecom API. Instead of writing REST integration code, you connect the server to Claude, OpenAI, or another MCP client and ask for what you need in natural language — search carrier rates, test voice routes, buy DID numbers or eSIMs, run HLR lookups, and monitor traffic. It ships with 55 tools and 7 guided workflow prompts, uses HTTP Digest Authentication with TLS 1.2+, and validates every input before it reaches the API.

Which AI assistants and tools work with it?

Any MCP-compatible client. Tested configurations include Claude Desktop, Claude Code (CLI), OpenAI Codex CLI, and Cursor. The server communicates over standard MCP stdio, so agent frameworks that support MCP — such as the OpenAI Agents SDK and Claude Agent SDK — can use it too.

What do I need to get started?

Three things: Python 3.10 or newer, a TelecomsXChange or NeuTRAFIX account, and your API credentials from the member dashboard (Account → API Settings). Setup takes about five minutes: clone the repo, install dependencies, copy .env.example to .env, add your credentials, and register the server with your AI client.

Does it work with NeuTRAFIX?

Yes. NeuTRAFIX runs the same platform API. Set TCXC_API_BASE_URL=https://apiv2.neutrafix.net in your .env and use your NTX credentials — everything else works identically.

Is it free to use?

The server itself is free and MIT-licensed. API usage is billed by TelecomsXChange at standard marketplace rates — voice, SMS, DID, and eSIM purchases made through the tools are real transactions on your TCXC account.

Can an AI agent make purchases autonomously?

Purchase tools (number_purchase, esim_purchase, esim_topup_purchase) execute real transactions against your account balance. MCP clients like Claude Desktop ask for your approval before each tool call by default; we recommend keeping approval prompts enabled for purchase and account-management tools.

How is it secured?

Credentials stay local in a gitignored .env file and are sent only to the TCXC API over HTTPS using HTTP Digest Authentication. The client enforces TLS 1.2+ with strong cipher suites, whitelists API endpoints, validates and sanitizes all inputs, rate-limits requests, and strips sensit