cx-agent-mcp

A small MCP server for a telecom support assistant. The assistant can look up customers, check balance and orders, suspend a lost SIM and open tickets, all through a REST backend. It also has a tool that reads a SIP trace and tells you why a call failed.

I spent a few years in VoIP support before moving to backend work, and most "the bot is broken" tickets I saw were really telephony or integration problems. So this project focuses on those two parts: calling backend APIs safely, and reading SIP traces.

What's inside

backend/api.py              mock telecom backend (FastAPI)
mcp_server/api_client.py    HTTP client: auth, timeouts, retries, idempotency keys
mcp_server/server.py        MCP tools, one resource, one prompt
mcp_server/sip_analyzer.py  SIP trace parser and rules
agent/chat.py               terminal chat client (Claude + the MCP server over stdio)
samples/trace_488.txt       example failed call
tests/                      pytest

Related MCP server: Nexlink Telecom MCP Server

Tools

Resource: policy://escalation. Prompt: support_agent.

How API calls are handled

• API key header on every request

• 3s timeout (configurable). A support bot can't keep a customer waiting

• Retries with backoff only on 429/502/503/504 and network errors

• 4xx errors are never retried

• Writes are retried only when they carry an Idempotency-Key, so a retry can't suspend a line twice or open two tickets

• Tools never raise. On failure they return ok: false, a sentence the bot can say, and a next step (offer_human_agent or ask_customer_to_check_input)

You can see this working by starting the backend with BACKEND_FAIL_RATE=0.3. About a third of the calls return 503 and the tools still answer.

SIP analyzer

Paste a text trace from an SBC, sngrep or Wireshark. It builds the ladder and checks for:

• 4xx/5xx final responses with what to look at (488 codec/SRTP mismatch, 403, 404 number format, 503...)

• 200 OK with no ACK (the call that drops after ~30 seconds)

• private IPs in the SDP c= line (one way audio behind NAT)

• only compressed codecs offered (bad for speech recognition)

• no telephone-event (DTMF won't reach the bot)

• more than one Call-ID (B2BUA legs)

Running it

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# terminal 1
uvicorn backend.api:app --port 8000     # swagger at http://127.0.0.1:8000/docs

# terminal 2, pick one
npx @modelcontextprotocol/inspector python -m mcp_server.server
python -m agent.chat                     # needs ANTHROPIC_API_KEY

Settings are read from environment variables, see .env.example.

Claude Desktop

{
  "mcpServers": {
    "cx-agent": {
      "command": "C:\\path\\to\\cx-agent-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\cx-agent-mcp",
        "BACKEND_URL": "http://127.0.0.1:8000",
        "BACKEND_API_KEY": "dev-secret-key"
      }
    }
  }
}

Things to try:

• "my number is 01001234567, how much balance do I have?"

• "where is ORD-5001?"

• "I lost my phone, stop my line"

• paste samples/trace_488.txt and ask why the call failed

Tests

pytest -q

The tool tests route httpx straight into the FastAPI app, so no server has to be running.

Next

• streamable HTTP transport

• OAuth2 client credentials instead of a static key

• FAQ search tool

• Arabic replies

• Genesys Cloud data action pointing at the backend