Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-telgea Find anna.lind@example.com's plan and check if her line is connected"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for the Telgea Open API (reference, OpenAPI spec), a business mobile operator with eSIM-based plans. It covers users and teams, user plans, lines and eSIMs, live connection status, number port-ins, usage records and analytics, data pools, rates and cost thresholds.
Tier | Tools |
Read (always on) |
|
Write ( |
|
Two-step ( |
|
SIM secrets ( |
|
Related MCP server: TCXC MCP Server
eSIM credentials are redacted everywhere else. Telgea returns the eSIM activation code and PIN/PUK on every line and plan read, and whoever holds the activation code can install the line on their own phone. Every tool except telgea_get_sim_credentials replaces those fields, but keeps the ICCID. That one tool has its own switch and requires a reason, so a gateway can also gate it with a separate group.
Changes that cost money or cannot be undone take two steps. These are new plans and lines, SIM swaps, port-ins, terminations and user deletion.
Prepare reads the target and returns an HMAC-signed preview with warnings. Nothing is sent.
Commit accepts only an unaltered operation that this server signed. It must arrive within 15 minutes and come from the user who prepared it, and its step must still pass the endpoint allowlist.
Commit is safe to repeat. The Idempotency-Key is derived from the operation hash, so committing twice makes Telgea replay its first answer instead of ordering a second line.
Port-ins are checked first. Telgea validates them during prepare, and invalid data stops the operation there.
The daily budget is protected. Telgea allows 1000 requests per key per 24 hours across every endpoint.
The server counts its own requests in a rolling window and refuses locally once TELGEA_DAILY_REQUEST_BUDGET is reached. TELGEA_BUDGET_STATE keeps the count across restarts.
Lists fetch one page unless maxPages asks for more, and reads are cached briefly (TELGEA_CACHE_TTL_MS). telgea_server_status shows what is left.
Writes need TELGEA_ENABLE_WRITES=true. The tool policy checks this, and so does every write path.
Attribution goes in the audit log. Telgea records every change against the API key. The JSONL audit (TELGEA_AUDIT_LOG) records:
the gateway-verified user (X-MCP-User) and the tool;
a SHA-256 hash of the identifiers, never the values;
the operation hash, for commits.
Forwarded identity requires the bearer token.
The HTTP transport refuses to start when TELGEA_TRUST_FORWARDED_USER=true but no MCP_HTTP_TOKEN is set.
With trust on, it refuses requests that lack X-MCP-User.
The token is compared in constant time.
Ids cannot redirect requests. An id with a separator, a dot segment, a query or percent-encoding is rejected before it reaches a URL. The client only calls /v1/… and sends the key only over HTTPS (or to loopback, for mocks).
Auth is the x-api-key header. Keys are organisation-scoped, and each endpoint needs its own permission (for example numbers:suspend or orders:cancel), so a key can be limited to the tiers you enable.
Errors are RFC 9457 application/problem+json. The server surfaces code, detail, fields and requestId, and the requestId is what Telgea support asks for.
Idempotency-Key is remembered for 24 hours per endpoint and replays the original outcome, including a failure.
/v1/usage takes a window of at most 31 days and uses a cursor. The other lists are page-numbered, with pageSize at most 50 for users, teams and user plans and at most 100 for lines and port-ins. The spec says 100 for user plans, but the live API answers 400 above 50.
Plans are addressed by their user id, and lines by their number id. A plan has a local and a travel number.
See .env.example. A production setup behind a gateway typically sets:
TELGEA_API_KEY=…
TELGEA_ENABLE_WRITES=true # or false for a read-only endpoint
TELGEA_ENABLE_SIM_SECRETS=false
TELGEA_TRUST_FORWARDED_USER=true
TELGEA_AUDIT_LOG=/data/audit.jsonl
TELGEA_BUDGET_STATE=/data/budget.json
TELGEA_OPERATION_SECRET=… # openssl rand -hex 32
MCP_HTTP_TOKEN=… # shared with the gatewayThe server runs as one container behind an authenticating MCP gateway that forwards the verified user as X-MCP-User. A typical access model:
Who | Gateway rule |
IT / telecom admins | the endpoint itself |
who may commit two-step changes | duty group on |
who may see eSIM activation codes | duty group on |
npm install
npm run dev # stdio
npm run dev:http # streamable HTTP on 127.0.0.1:3000/mcp (stateless)
npm test
TELGEA_API_KEY=… npm run smoke:live # read-only, about 10 requests, prints shapes and counts onlyDocker images: ghcr.io/borgels/mcp-server-telgea (published on push to main).
Step 2 of 2: send a prepared operation, unchanged, with its operationHash. Valid for 15 minutes, only for the user who prepared it. Requires TELGEA_ENABLE_WRITES=true on the server. Committing the same operation twice replays the first result (idempotency key from the hash).
Inputs: operation (required), confirmOperationHash (required).
Create a team, optionally with members. Requires TELGEA_ENABLE_WRITES=true on the server.
Inputs: name (required), emoji, userIds, costCode.
Create a user (employee) in the organisation. Does not order a plan — that is telgea_prepare_change kind=create_user_plan. Requires TELGEA_ENABLE_WRITES=true on the server.
Inputs: email (required), lastName (required), firstName (required), teamId, +2 more.
Find one user’s plan by email, phone number (E.164) or ICCID. eSIM activation codes and PIN/PUK are redacted; use telgea_get_sim_credentials if you are allowed to see them.
Inputs: email, iccid, msisdn.
One line: state, timestamps (activated, termination scheduled), current and previous SIMs. eSIM activation codes and PIN/PUK are redacted; use telgea_get_sim_credentials if you are allowed to see them.
Inputs: numberId (required).
Live network status of a line: attached or not, last seen, serving network, 2G–5G, APN, IMEI. For “my phone has no signal” support. IMEI and IP address are device data; share only with the line’s holder or IT.
Inputs: numberId (required).
Status of one port-in (CREATED → SUBMITTED → ACCEPTED → SUCCEEDED, or REJECTED/FAILED with reason).
Inputs: portInId (required).
The fields a number port-in needs for a country, as a field list or a JSON Schema.
Inputs: countryCode (required), format.
eSIM activation code (LPA string / QR content) and PIN/PUK codes for one line. Requires TELGEA_ENABLE_SIM_SECRETS=true on the server. Anyone with the activation code can install the line on their own phone. Give it only to the line’s holder.
Inputs: reason (required), numberId (required).
Aggregated data, voice and SMS consumption per day or month, with highest/lowest/average. Filter by user, number or serving country. Cheapest way to answer “how much did we use”.
Inputs: endDate (required), interval (required), startDate (required), msisdn, +3 more.
A user’s effective cost threshold for DATA, VOICE (international calls), SMS or MMS, current spend this period, and whether usage is paused.
Inputs: userId (required), usageType (required).
Full plan for a user: status, local and travel numbers with line state and SIM ICCID. eSIM activation codes and PIN/PUK are redacted; use telgea_get_sim_credentials if you are allowed to see them.
Inputs: userId (required).
Cost thresholds (monthly spend caps) for the organisation, a team or a user.
Inputs: teamId, userId, usageType.
Members of a data pool with each one’s data use.
Inputs: poolId (required).
Shared data pools: region, total/consumed/remaining GB, expiry, whether restrictions are active.
Inputs: no named parameters.
List lines (numbers) with type local/travel, state, ICCID and holder. Filter by msisdn, iccid, userId, type or state. eSIM activation codes and PIN/PUK are redacted; use telgea_get_sim_credentials if you are allowed to see them. Filtering by state costs Telgea more than other filters.
Inputs: page, type, iccid, state, +6 more.
All port-in attempts for one line.
Inputs: numberId (required), page, maxPages, pageSize.
Pay-as-you-go retail rates for a home market: international voice/SMS/MMS or roaming data, per destination country.
Inputs: type (required), market (required), asOfDate, direction, +1 more.
List teams (billing/access groups) with member counts and cost codes.
Inputs: page, maxPages, pageSize.
Raw call, SMS, MMS and data records with price: timestamps, amount, roaming/international class, counterparty. Window up to 31 days; cursor paging. Each call spends Telgea requests from the 1000/day budget shared by everyone using the key. Records include who called whom. Use telgea_get_usage_analytics for totals; reach for raw records only when the detail is needed.
Inputs: endDate (required), startDate (required), cursor, userId, +2 more.
List subscriptions (user plans): user, status (ACTIVE, PROVISIONING, PORTING, TERMINATING…), local number and team. Sortable. Each call spends Telgea requests from the 1000/day budget shared by everyone using the key.
Inputs: page, orderBy, maxPages, pageSize, +1 more.
List the organisation’s users (employees): name, email, team, employee id, cost code. Filter by exact email or employeeId. Each call spends Telgea requests from the 1000/day budget shared by everyone using the key.
Inputs: page, email, maxPages, pageSize, +1 more.
Step 1 of 2 for what costs money or cannot be undone: create_user_plan, add_line, replace_sim, terminate_line, terminate_plan, delete_user, submit_port_in, discard_port_in. Returns a signed preview; nothing is sent. Requires TELGEA_ENABLE_WRITES=true on the server. Show the preview and warnings to the user and get an explicit yes before committing.
Inputs: kind (required), reason (required), fields, msisdn, +8 more.
Remove a spend cap, releasing paused usage. Requires TELGEA_ENABLE_WRITES=true on the server.
Inputs: usageType (required), teamId, userId.
Find the Telgea tool to use. Does not call Telgea. Discovery only.
Inputs: limit, query.
Show which tiers are enabled on this instance and how much of the daily request budget is used. Does not call Telgea. Discovery only.
Inputs: no named parameters.
Set a monthly spend cap on DATA, VOICE (international), SMS or MMS for the organisation, a team or a user. Reaching it pauses that usage. Requires TELGEA_ENABLE_WRITES=true on the server. May apply from next month; the result says so (appliesFromNextMonth).
Inputs: maxAmount (required), usageType (required), teamId, userId.
Stop or restore mobile data on one line (numberId) or on every line of a user (userId). Calls and SMS keep working. Requires TELGEA_ENABLE_WRITES=true on the server. Confirm with the user first.
Inputs: action (required), reason (required), userId, numberId.
Suspend a line (no calls, SMS or data — e.g. a lost phone) or restore a suspended line. Requires TELGEA_ENABLE_WRITES=true on the server. Suspending cuts the holder off completely until restored. Confirm with the user first.
Inputs: action (required), reason (required), numberId (required).
Rename a team, change its cost code/emoji, or replace its member list. Requires TELGEA_ENABLE_WRITES=true on the server. userIds replaces the whole member list.
Inputs: teamId (required), name, emoji, userIds, +1 more.
Change a user’s name, email, team, cost code or employee id. Requires TELGEA_ENABLE_WRITES=true on the server.
Inputs: userId (required), email, teamId, costCode, +3 more.
Check port-in data against Telgea’s rules without submitting anything. Does not submit. Submitting goes through telgea_prepare_change kind=submit_port_in.
Inputs: type (required), fields (required), msisdn (required), countryCode (required), +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 32 tools
Most tools target a distinct resource+action, and descriptions explicitly route between near-neighbours (e.g. list_usage vs get_usage_analytics, list_lines vs get_line). The main soft spots are find_user_plan vs get_user_plan vs list_user_plans, and get_user_cost_threshold vs list_cost_thresholds, where boundaries require reading the descriptions to resolve.
Every tool uses a uniform telgea_ verb_noun snake_case pattern (get_, list_, create_, update_, set_, remove_, find_, validate_, prepare_, commit_). Verb choices are semantically consistent across resources, so an agent can predict names.
32 tools is heavy and sits above the comfortable range, though the domain genuinely spans users, teams, lines, plans, SIMs, usage, port-ins, thresholds, pools and meta-discovery. Some consolidation is possible (e.g. find/get user plan, the several threshold readers), but each tool maps to a real operation rather than filler.
Coverage is broad and lifecycle-aware: writes are funnelled through the prepare/commit two-step, and reads cover users, teams, lines, plans, SIM credentials, usage, port-ins, thresholds, pools and rates. Minor gaps remain — no team deletion, no data-pool creation/update, no direct user deletion outside prepare_change — but these are workable.
Manage your Telvana AI voice, SMS and chat agents, conversations, campaigns and outbound calls.
Give your AI assistant a real phone line. Place and end real phone calls with AI voice agents, read call transcripts, run a live two-way interpreter between two people who share no language (31 languages, browser link or phone), create and edit voice agents, and search, buy and bind phone numbers in 21 countries. OAuth 2.1 with PKCE — the model never sees your API key; a read-only scope is available. Pay as you go from $0.10/min, $5 free credit for new accounts.
Give AI agents secure access to RevDesk calling, SMS, phone numbers, caller IDs, and usage.
Tenant-scoped control plane over the TeleQuick platform's full API surface
