PacketExchange MCP Server

Top-100 metric breakdown grouped by customer, supplier, or destination (the first 3 digits of the dialled number). Find the most/least profitable customers, worst-quality suppliers, or costliest destinations. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

Unified P&L + quality KPIs (revenue, cost, margin, marginPct, calls, answered, minutes, ASR, ACD, SMS count, avg PDD) across all operator CDR traffic for a date range. The go-to health snapshot. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

AR aging summary: total outstanding, open count, and current/1-30/31-60/61-90/90+ buckets across open/partial/overdue invoices. Key collections-health read. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Point a customer at its routing: dialplan, route group, failover route group, LCR strategy override (cheapest|best_quality|balanced), or a direct supplier (one marketplace route OR one vendor trunk, not both). Only the fields you pass change: omitted fields keep their current value, and null clears a field. Writes the customer's first trunk (a customer with no trunk is refused); multi-trunk customers are configured per trunk in the dashboard. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Bulk upsert the operator's retail SELL deck (A-Z), de-duped last-wins, up to 50000 rows. Fires the sell_rate.changed webhook. The efficient way to load or refresh retail pricing. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Bulk upsert a supplier trunk's A-Z COST deck (paste/CSV rows), de-duped last-wins, up to 50000 rows. Price increases may be queued until the supplier's rate-notice period ends instead of applying at once. The efficient way to load or refresh vendor pricing. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Create a switch-native customer and mint its first API key (returned ONCE, with sipPassword). Set markupPct, credit limit, margin floor, spend and concurrency caps, CPS, blocked prefixes, tax details and portalEmail. externalRef is an idempotency key: repeating a create with the same externalRef returns the existing customer WITHOUT a new API key or sipPassword. The provisioning entry point for onboarding a buyer. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

Two steps, like a human review. Step 1 (read-only, writes nothing): call WITHOUT review_token to get a preview of the AR invoice for a customer over a period from settled CDR usage (itemized voice + SMS lines, totals, anything unrated) plus a reviewToken. Step 2 (MUTATES STATE, irreversible): call again with the SAME arguments and review_token to issue it; this allocates the invoice number, claims the usage and emits invoice.created. If the usage changed since the preview the issue is refused (409) with a fresh preview. Issuing does not send the invoice to the customer. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Generate an AP payable for a supplier trunk over a period from CDR seller-credit cost. The core settlement action for what the operator owes vendors. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Create an external supplier vendor trunk (SIP host/port/transport, auth, codecs, default rate, capacity, CPS, settlement mode) and/or its SMS delivery (HTTP URL or SMPP bind). Needs a label plus at least one way to deliver traffic: sipHost, smsDeliveryUrl, or smppHost with smppSystemId. A new trunk may be held as draft until it passes readiness checks. The provisioning entry point for a termination vendor. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

List the 100 most recent fraud events (newest first) with score, action (flag|block), destination, reasons, and customer label. Monitor and triage abuse. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

List all sell-side customers (sub-accounts) with balance, credit limit, markup, margin floor, spend caps, concurrency, and status. Core inventory read for who is connected. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

List AR invoices with customer/status filters, pagination, and computed overdue flag. Survey receivables. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

List all buy-side supplier vendor trunks with SIP egress config, default rate, capacity, CPS, settlement mode, and status. Core inventory read for termination options. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

Read-only routing preview for a dialed number: resolves the dialplan (matched rule, block verdict, translated number, out-CLI) and returns the ordered supplier failover chain with per-attempt price and prefix match. No side effects: the single best tool to sanity-check routing before real traffic. Optionally scope to a customer via sub_account_id (their assigned dialplan) and customer_trunk_id (that trunk's restrictions; default is the customer's single active trunk). Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Run bilateral netting for a counterparty over a period: offsets AR (their invoices) against AP (their payables), returning net amount and direction (settled|receivable|payable). Key settlement automation. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Replace ALL entries of a route group with an ordered supplier list (per-prefix, with failover priority, load-balance weight, and ASR/PDD gates). The primary tool to (re)configure LCR/failover routing. Enforces exactly-one-target (routeId XOR vendorTrunkId) and ownership. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

MUTATES STATE. Update per-operator fraud screening: enable/disable, block/alert score thresholds (1-100), and high-risk destination prefixes. highRiskPrefixes REPLACES the whole list; an empty list reverts to the platform defaults. Tune protection. Requires an active Switch subscription (402 SWITCH_SUBSCRIPTION_REQUIRED otherwise) and a full-access API key (scoped keys need switch:manage). Test keys are NOT sandboxed here: they read and change your live Switch data.

Read-only. Current account balance and test credit, in USD, plus their sum for reference. Only the balance pays for live calls and messages; test credit covers test API keys (simulated traffic) only. Requires the account:read scope (full-access keys have it).

Returns one call placed with wmmn_make_call (or POST /comms/calls): live status (queued, ringing, answered, then completed, no_answer, busy or failed), timestamps, duration, exact USD cost, the hangup reason in plain words, and the keypad digits collected by gather actions. Free. Requires the voice:send scope.

Read-only. List the routes you have connected (your purchases, newest 50), with status, per-unit USD pricing and your SIP credentials (username + password) for each. Requires a FULL-ACCESS API key (one created with no scope restrictions): because the response contains SIP passwords, every scoped key is refused with 403.

Read-only, free, no key needed. Search and filter live voice/SMS termination routes on the PacketExchange marketplace. By default it returns what the website shows: one row per route and mobile network, routes we have PROVEN first (tested_desc), each with two platform-measured marks: route_status (proven = a real call or our test connected to that network recently; weak = it connects but few calls do; at_risk = the latest test failed; untested = no evidence yet, not a fault) and caller_id (full = the caller ID arrived intact on a real phone on that network; replaced; none; untested). Every listing also carries a verification tier for the whole route (owner, 16 Oct 2026), and every view lists the best tier first: cli = "International CLI" (our international caller-ID test showed the exact number we sent, in full), ncli = "NCLI" (the test reached the phone with a different number or none), connected = "Qualified" (a real answered call or passed test, no caller-ID result), not_verified = "Untested" (not tested by us yet, or the latest test failed; new listings start here; still buyable). Quoted names are what the marketplace shows; the values are stable keys. Use verification=<tier> to keep one tier, or tested=true / verified_cli=true to keep only proven rows. Prices are USD per minute (voice) or per message (SMS). ASR/ACD figures are the SELLER-DECLARED expected values, not platform-measured. Route quality tiers (route_type): direct | premium | standard | ncli (NCLI = no caller ID: lowest cost, more intermediate carriers, and the called party does not see the number). Set per_network=false for one row per listing (a multi-destination A-Z deck then shows only its cheapest "from" rate, so check wmmn_route_details). CALLER ID ORIGIN: some sellers price by where the call originates, judged by the caller ID sent (From and P-Asserted-Identity). origin_policy "dual" = two prices: origin_price applies when the call presents a VALID caller ID from origin_group (EEA = the 27 EU countries, Iceland, Liechtenstein, Norway), price applies to every other call (another country, no caller ID, or an invalid one). "origin_only" = the route carries only calls with a caller ID from origin_group; other calls go to your next route. Filter with origin_policy.

Read-only. Recent billing transactions for your account, newest first, amounts in USD (charges are negative, credits/top-ups positive). Types: topup, charge, credit, payout, platform_fee, test_credit. Requires the account:read scope.

SPENDS MONEY. Places a REAL outbound phone call and CHARGES your balance for a connected call: billable minutes (per the route billing increment) at the route price, plus a platform fee of 2% of the carrier cost, capped at $0.001 per call or message (0.5%, same cap, when the traffic runs over your own SIP trunk; no fee when the carrier cost is 0). Unanswered calls cost nothing. The worst-case cost for max_duration is reserved from your balance up front and the unused part refunded on hangup. The call is placed ASYNCHRONOUSLY: this tool waits up to wait_seconds (default 20) for it to finish, then returns either the final result (status completed, no_answer, busy or failed, with duration, cost, plain-words hangup reason and any gathered digits) or, if the call is still running, its call_id and live status - check it later with wmmn_get_call. Optional actions make the answered call speak (say, in en/es/fr/de/pt/hi), play an https MP3, collect keypad digits (gather), pause or hang up, in order; the call ends when they finish; no charge for the speech. Omit route_id to Smart-Route across the public marketplace (no purchase needed); a route_id must be a route you have purchased. A test key (wmmn_test_sk_...) simulates against test credit with no real telephony and runs no actions. Requires the voice:send scope.

Read-only, free. Live marketplace snapshot: total routes, destinations, voice and SMS route counts, market status and as-of time. When the connection carries an API key, the averages are included too (capacity, average and measured ASR, ACD and USD price); without a key only the counts are returned. 24h trading volumes are not part of this summary.

PROVISIONING ACTION (not read-only). Connect a marketplace route to your account. Connecting is free, with no upfront charge, but it provisions live SIP credentials, and any traffic you then send over the route CHARGES your balance per minute/message at the route price. Requires a LIVE key with the purchases:write scope: a test key (wmmn_test_sk_...) is refused with 400 "Route purchases require a LIVE API key". Your email must be verified; a private route needs an access grant from its seller; US voice routes need a complete STIR/SHAKEN profile and start as pending_review; connecting a route you already hold returns 409. The response includes your SIP username and password, shown once here (also retrievable later with wmmn_list_purchases on a full-access key).

Read-only, free, no call placed. Preview which route Smart Routing would pick for a destination, plus up to 4 ranked alternatives. It ranks every active public marketplace route for that destination together with any private routes you have purchased. Requires an API key with the routes:read scope (full-access keys have it).

Read-only, free, no key needed. Full details for one route — USD pricing, billing increment, seller-declared expected ASR/ACD/PDD, CLI type, capacity, and the first-party Exchange Score plus seller trust profile. originPolicy / originGroup / originPricing say whether the route is priced by caller ID origin: with "dual", originPricing.originFrom is the lowest price for calls presenting a valid caller ID from originGroup (EEA), and pricePerUnit / the deck rates are the International price for every other call; "origin_only" carries only calls with a caller ID from originGroup.

SPENDS MONEY. Sends a REAL SMS and CHARGES your balance: the route price per segment, plus a platform fee of 2% of the carrier cost, capped at $0.001 per call or message (0.5%, same cap, when the traffic runs over your own SIP trunk; no fee when the carrier cost is 0). Long messages are split into segments (160 GSM-7 characters, 153 per part when split; 70 Unicode, 67 per part). Returns message id, segment count and exact USD cost. The returned status is carrier ACCEPTANCE, not handset delivery; delivery receipts are not returned by this tool. Omit route_id to Smart-Route across the public marketplace (no purchase needed); a route_id must be a route you have purchased. A test key (wmmn_test_sk_...) simulates against test credit with no real delivery. Requires the sms:send scope.

SPENDS MONEY. Places a REAL short phone call (capped at 120 seconds) and speaks a one-time passcode digit by digit ("Your {brand} verification code is 4, 8, 2, 9, 1, 3. Again, ..."), repeated (default twice), then hangs up. Billed like any API call: billable minutes at the route price, plus a platform fee of 2% of the carrier cost, capped at $0.001 per call or message (0.5%, same cap, when the traffic runs over your own SIP trunk; no fee when the carrier cost is 0); no text-to-speech surcharge. Returns as soon as the call is dialled (status "initiated") with a voice_otp id; the final outcome and cost are recorded later (GET /api/v1/comms/voice-otp/{id} in the REST API). Omit code to have one generated; it is returned only when return_code is true. Limits: 5 per number per hour, 30 second resend cooldown, 20 per number range per hour, 1000 per account per day; embargoed, high-risk and do-not-contact numbers are refused. A test key (wmmn_test_sk_...) simulates with no real call and returns status "accepted" with simulated: true. Requires the voice:send scope. For send-and-check, prefer wmmn_verify_start with channel "voice".

SPENDS MONEY FROM AN ON-CHAIN WALLET. Funds your PacketExchange balance with real USDC on Base over the x402 protocol. Step 1 is safe/read-only: call with just amount_usd to receive the payment requirements (HTTP 402 challenge naming the network, USDC amount and payTo address; nothing is charged). Step 2 MOVES FUNDS: sign the EIP-3009 USDC transferWithAuthorization, base64-encode it, and call again passing it as payment_header; the transfer settles on-chain and your balance is credited. Amounts are USD, min $5, max $50,000, subject to account verification (KYC) and top-up velocity limits. The credit goes to your LIVE balance whichever key you use: a test key does not simulate this. Requires the billing:write scope.

Free, no send. Checks a code the user entered against a verification from wmmn_verify_start. Returns status approved | denied | expired | max_attempts and attemptsRemaining. Only "approved" proves the user holds the number. Each wrong code uses one of 5 attempts; an approved verification cannot be approved again (a repeat check is denied with reason already_used). Check with the same kind of key (test or live) that started the verification. Requires the verify:write scope.

SPENDS MONEY. Starts a phone-number verification: generates a one-time code, stores only a keyed hash of it, and sends it by SMS or by a voice call that speaks it. Billed exactly like a normal SMS or API call: the route price, plus a platform fee of 2% of the carrier cost, capped at $0.001 per call or message (0.5%, same cap, when the traffic runs over your own SIP trunk; no fee when the carrier cost is 0). Returns a verification_id (never the code on a live key). The code expires after expiry_seconds (default 600), allows 5 check attempts and approves once. Rate limited: 5 starts per number per hour, 30 second resend cooldown, 20 per number range per hour, and 1000 per account per day; embargoed, high-risk premium and do-not-contact destinations are refused. A test key simulates the send and returns testCode so the flow can be completed. Requires the verify:write scope.