Skip to main content
Glama

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

Tool

Kind

Notes

lookup_customer

read

accepts 010..., 0020... or +20...

get_line_status

read

balance, data left, line status

get_order_status

read

validates the order id before calling the API

suspend_line

write

refuses unless customer_confirmed is true; idempotent

create_ticket

write

handover note for the human agent; idempotent

analyze_sip_trace

local

ladder, codecs, media IPs, likely cause

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers