Telekom agentic commerce — demo MCP server

A runnable MCP server that turns the static prototype into a real journey you can drive by talking to Claude, Gemini or ChatGPT.

Nothing here touches a Telekom system. Every tool answers from the markdown files in catalogue/, so the offer can be changed by editing a file and restarting — no code, no deployment, no engineer.

server.py              the whole server: 9 tools, 3 prompts, 8 UI widgets
catalogue/tariffs.md   11 tariffs across mobile, fixed and TV/OTT
catalogue/devices.md   6 devices, priced per tariff
catalogue/consents.md  TKG 54, AGB, Widerruf, card mandate, and per-line-type extras

Run it

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python server.py                      # stdio, for a local desktop client
python server.py --http --port 8000   # remote, for a custom connector
python server.py --http --no-mcp-ui   # ...without the in-band ui:// widget

The HTTP endpoint is http://127.0.0.1:8000/mcp.

To reach it from a hosted assistant temporarily, put a tunnel in front:

npx cloudflared tunnel --url http://localhost:8000

Use the https://….trycloudflare.com/mcp URL it prints. This is fine for a live demo but the URL is random and dies when your machine or the tunnel process stops.

Deploy for real (Render)

Cart state lives in memory in a single Python process (see CARTS in server.py), so this needs one persistent instance, not an autoscaled or serverless one. Render’s free web service tier fits: one always-running container, a stable HTTPS domain, no card required.

This repo already includes render.yaml and .python-version (mcp>=2.2.0 requires Python 3.10+, pinned here to 3.11.9).

1. Push this folder to a new GitHub repo.
2. On render.com, New + → Blueprint, connect the repo. Render reads render.yaml and creates the web service automatically (build: pip install -r requirements.txt; start: python server.py --http --host 0.0.0.0 --port $PORT).
   • No render.yaml/Blueprint access? Use New + → Web Service instead and paste the same build/start commands by hand.
3. Deploy. Render gives you https://.onrender.com.
4. Your MCP endpoint is https://.onrender.com/mcp.

Verify it’s alive:

curl -i https://.onrender.com/mcp

(A 4xx/406 response is expected for a plain GET — the endpoint only speaks JSON-RPC over POST. Anything other than a connection error or 502 means the process is up.)

Then connect it: in Claude, Settings → Connectors → Add custom connector, paste that /mcp URL.

Free-tier caveats: the service spins down after ~15 minutes idle and takes 30–60s to wake on the next request (the first tool call in a new session may time out or feel slow — retry it). Every restart or redeploy also wipes