# Tcxc Mcp Server

> MCP server for the TelecomsXChange (TCXC) API — give Claude, OpenAI, Cursor, and any MCP client AI access to wholesale voice termination, SMS, DID numbers, eSIM, and HLR lookups. 55 telecom tools.

- **Type:** MCP server
- **Install:** `agentstack add mcp-telecomsxchangeapi-tcxc-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TelecomsXChangeAPi](https://agentstack.voostack.com/s/telecomsxchangeapi)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TelecomsXChangeAPi](https://github.com/TelecomsXChangeAPi)
- **Source:** https://github.com/TelecomsXChangeAPi/tcxc-mcp-server
- **Website:** https://www.telecomsxchange.com

## Install

```sh
agentstack add mcp-telecomsxchangeapi-tcxc-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# TCXC MCP Server

[](LICENSE)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)

The **TCXC MCP Server** is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects AI assistants — Claude, OpenAI, Cursor, and any MCP-compatible client — to the [TelecomsXChange (TCXC)](https://www.telecomsxchange.com) wholesale telecommunications marketplace. It exposes **55 tools and 7 guided workflows** for voice termination, SMS messaging, DID phone numbers, eSIM data packages, HLR lookups, and carrier account management, so telecom operators and developers can run wholesale telecom operations in plain English.

## What Can AI Assistants Do With It?

| Capability | What your AI assistant can do |
|---|---|
| **Voice Termination** | Search carrier rates by prefix, run A/B route test calls, analyze CDRs and call quality (ASR/ACD) |
| **SMS Services** | Compare global SMS termination rates, review delivery history and traffic summaries |
| **DID Numbers** | Search, purchase, and configure virtual phone numbers (voice, SMS, fax capable) |
| **eSIM Exchange** | Browse data packages by country, purchase eSIMs, top up, and track orders |
| **Number Intelligence** | Live HLR lookups, portability data, and fraud/reputation scoring |
| **Financial** | Check buyer/seller balances and payment history in real time |
| **Account Management** | Provision SIP/SMS sub-accounts, manage IPs, block/unblock accounts |
| **Analytics** | Live calls, top routes, traffic summaries, and performance insights |

Example requests once connected:

> "What's my TCXC account balance?"
>
> "Search voice rates for prefix 44 and compare the top 3 carriers"
>
> "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)](https://www.telecomsxchange.com) or [NeuTRAFIX (NTX)](https://www.neutrafix.net) account.

```bash
# 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](https://members.telecomsxchange.com) → Account → API Settings
- **NeuTRAFIX**: [members.neutrafix.net](https://members.neutrafix.net) → Account → API Settings

Edit `.env`:

```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:

| AI Client | Setup |
|---|---|
| Claude Desktop | JSON config (below) |
| Claude Code | `claude mcp add` one-liner |
| OpenAI Codex CLI | `codex mcp add` one-liner |
| Cursor | JSON config (below) |
| Any MCP client | Point it at `start_mcp_server.sh` |

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`

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

#### Claude Code (CLI)

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

#### OpenAI Codex CLI

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

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

```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):

```json
{
  "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

```bash
# 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:

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

Interactive commands:
- `list_tools` - Show all available tools
- `call_tool  ` - Execute a tool
- `list_prompts` - Show guided workflows
- `get_prompt  ` - Get workflow guidance

## Available Tools

### Voice Operations
```python
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
```python
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
```python
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
```python
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
```python
buyers_balance()
seller_balance()
buyers_payhistory(date_from="2026-01-01", date_to="2026-01-31")
buyers_account_list()
```

### Utilities
```python
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](docs/TOOLS.md) 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](PROMPTS.md) for the full guide.

## Troubleshooting

### Server won't start
```bash
# Check environment variables
cat .env
```
Confirm all four credential variables are set (buyer and seller).

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

### Import errors
```bash
# 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

```bash
# 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](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 sensitive data from error messages and logs. See [SECURITY.md](SECURITY.md).

### What is TelecomsXChange?

[TelecomsXChange](https://www.telecomsxchange.com) is a wholesale telecommunications marketplace where licensed carriers, operators, and communication service providers buy and sell voice termination, SMS, DID numbers, and eSIM data packages. Buyers get transparent per-route pricing with quality metrics (ASR/ACD); sellers reach a global base of interconnected buyers through one API.

## License

MIT License - see [LICENSE](LICENSE) file

## Support

- **Issues**: [GitHub Issues](https://github.com/TelecomsXChangeAPi/tcxc-mcp-server/issues)
- **TCXC Support**: [telecomsxchange.com/contact](https://www.telecomsxchange.com/contact)
- **API Docs**: [apidocs.telecomsxchange.com](https://apidocs.telecomsxchange.com)
- **Dashboard**: [members.telecomsxchange.com](https://members.telecomsxchange.com)

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

---

**Built with the** [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | **Powered by** [TelecomsXChange](https://www.telecomsxchange.com)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TelecomsXChangeAPi](https://github.com/TelecomsXChangeAPi)
- **Source:** [TelecomsXChangeAPi/tcxc-mcp-server](https://github.com/TelecomsXChangeAPi/tcxc-mcp-server)
- **License:** MIT
- **Homepage:** https://www.telecomsxchange.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-telecomsxchangeapi-tcxc-mcp-server
- Seller: https://agentstack.voostack.com/s/telecomsxchangeapi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.