Carrier MCP: Give Your AI Agent Global Connectivity
Carrier MCP — natural language control of your MVNO/eSIM fleet.
Community: Submitted by a user or imported; check the owner before granting accessOnlineNo sign-inGlobalFreeRead-only
What it can do
- List Reseller Accounts: Use this to enumerate all accounts (sub-resellers or customer accounts) under a reseller. Returns each account's name, ID, current balance, package-only flag, and account type.
- Modify Account Balance: Use this to adjust or set the monetary balance on a reseller account. 'adapt' mode adds (positive amount) or subtracts (negative amount) from the current balance; 'set' mode re
- Get Reseller Info: Use this to retrieve full details for a reseller: main info, traffic configuration, charging info, contact info, and active pricing plans. Params: `resellerId` (integer, optional —
What data it sees
Do you need an account
No: the server works without sign-in
Carrier MCP — natural language control of your MVNO/eSIM fleet. 52 tools (43 OCS API wrappers + 8 AI intelligence + 1 OCS event history), 5 prompts, OAuth 2.1 + PKCE. Streamable HTTP on Cloudflare Workers.
How to connect
How to connect Carrier MCP: Give Your AI Agent Global Connectivity to Claude
The server address to paste into Claude settings:
https://carrier.run.tools
- Open Claude (claude.ai or the desktop app).
- Go to Settings → Connectors.
- Click Add custom connector.
- Paste the server address copied below into Remote MCP server URL and click Add.
- In a chat, click + → Connectors and switch the new connector on.
Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.
Authorization
After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.
How to connect Carrier MCP: Give Your AI Agent Global Connectivity to ChatGPT
The server address to paste into ChatGPT settings:
https://carrier.run.tools
- Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
- Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
- Open Settings → Connectors and click Create.
- Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
- Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
- In a new chat open + → Apps/Connectors and enable the connector.
OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.
Authorization
On first use ChatGPT opens the service's sign-in window. Sign in and approve access.
How to connect Carrier MCP: Give Your AI Agent Global Connectivity to Cursor
The server address to paste into Cursor settings:
https://carrier.run.tools
Fastest: click Open in Cursor below and confirm the prompt.
Manually:
- In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
- Paste the JSON copied below into
~/.cursor/mcp.json(per project:.cursor/mcp.jsonin the repo root). - Save the file. The server appears in the MCP list; authorize it there if asked.
Authorization
If the service needs sign-in, an authorize button appears next to the server in the MCP list.
Server tool list (60)
Raw names from tools/list. Only developers need these.
| list_reseller_accounts | Use this to enumerate all accounts (sub-resellers or customer accounts) under a reseller. Returns each account's name, ID, current balance, package-only flag, and account type. Params: `resellerId` (integer, optional — omit to list accounts under the token owner's reseller). Returns: array of account records, each containing `accountId`, `name`, `balance`, `type`. Do NOT use this to fetch a single subscriber's details — use `get_subscriber` instead. Do NOT use this to check eSIM activation counts — use `esim_status_per_account` for that. |
| modify_account_balance | Use this to adjust or set the monetary balance on a reseller account. 'adapt' mode adds (positive amount) or subtracts (negative amount) from the current balance; 'set' mode replaces the balance with the exact amount. Every change is logged as a transaction. Params: `accountId` (integer account ID from `list_reseller_accounts`), `amount` (number), `mode` ('adapt' | 'set'). Returns: updated account balance record with the transaction ID. Do NOT use this to modify a subscriber's personal balance — use `modify_subscriber_balance` instead. Always call `list_reseller_accounts` first to confirm the target accountId before executing. |
| get_reseller_info | Use this to retrieve full details for a reseller: main info, traffic configuration, charging info, contact info, and active pricing plans. Params: `resellerId` (integer, optional — omit to return the token owner's reseller). Returns: reseller object with `id`, `name`, `balance`, `pricingPlan`, `contactInfo`, and more. Do NOT use this to list all accounts under a reseller — use `list_reseller_accounts` for that. |
| esim_status_per_account | Use this to get eSIM status counts broken down by account: active, suspended, inventory (not yet activated), and other states. Good for fleet health dashboards and capacity planning. Params: `accountId` (integer, optional — omit for all accounts under the reseller). Returns: array of per-account objects with `accountId`, `active`, `suspended`, `inventory`, `other`. Do NOT use this to check a single subscriber's status — use `get_subscriber` for that. Do NOT use this for billing or balance checks — use `list_reseller_accounts` for balances. |
| list_sponsors | Use this to list all sponsor networks (eSIM sponsor carriers) available to this reseller. A sponsor defines which physical network infrastructure backs a given eSIM profile. Params: `resellerId` (integer, optional — omit to use the token owner's reseller). Returns: array of sponsor records with `sponsorId`, `name`, and coverage metadata. Do NOT use this to list steering lists or network profiles — those are separate concepts. Use `list_steering_lists` to see operator preference configurations. |
| list_steering_lists | Use this to retrieve all network steering lists configured for this reseller. A steering list is a named configuration of excluded and priority mobile operators that controls which networks an eSIM prefers to roam onto — the primary mechanism for network quality optimisation and cost control. Call this before `modify_subscriber_steering_list` to obtain valid steering list IDs. Params: `resellerId` (integer, optional — omit to use the token owner's reseller). Returns: array of steering list records with `steeringListId`, `name`, and configured operators. Do NOT use this to assign a steering list to a subscriber — use `modify_subscriber_steering_list`. Do NOT use this to push a steering change to a device — use `push_steering_to_subscriber` after assignment. |
| get_subscriber | Use this as the primary lookup for a single subscriber by ICCID or MSISDN. Returns the complete subscriber record: status, balance, assigned account, contact info, IMSI, simId, steering list, active pricing plan, and traffic restriction flags. Params: `iccid` (20-digit ICC identifier, optional) OR `msisdn` (E.164 phone number, optional) — provide at least one. Returns: full subscriber object. Key fields: `status` (ACTIVE/SUSPENDED/TERMINATED), `balance`, `imsi`, `simId`, `steeringListId`. Do NOT use this for bulk lookups — use `list_subscribers` with filters for that. |
| list_subscribers | Use this to list subscribers with optional filters and pagination. Good for fleet enumeration, bulk status checks, and finding subscribers by account or status. Params: `accountId` (integer, filter by account), `status` (string, e.g. 'ACTIVE'/'SUSPENDED'), `offset` (integer, for pagination — default 0), `limit` (integer, max results — always set to avoid unbounded fetches; recommended max 100 per call). Returns: array of subscriber summary records with ICCID, status, and account. Do NOT use this to fetch full details for a specific subscriber — use `get_subscriber` for that. |
| modify_subscriber_balance | Use this to adjust or set the monetary balance for an individual subscriber. 'adapt' mode adds (positive) or subtracts (negative) from the current balance; 'set' mode replaces the balance with the exact amount provided. Params: `iccid` (subscriber identifier), `amount` (number), `mode` ('adapt' | 'set'). Returns: updated subscriber balance. Do NOT use this to modify an account-level balance — use `modify_account_balance` for that. Always call `get_subscriber` first to capture the current balance before adjusting. |
| modify_subscriber_status | Use this to change the OCS lifecycle status of a subscriber. Common transitions: ACTIVE → SUSPENDED (pause without losing packages), SUSPENDED → ACTIVE (reactivate), ACTIVE/SUSPENDED → TERMINATED (irreversible). WARNING: TERMINATED status is permanent — the subscriber record cannot be reactivated. Params: `iccid` (subscriber identifier), `status` (new status string, e.g. 'ACTIVE', 'SUSPENDED', 'TERMINATED'). Returns: updated subscriber record with the new status. Do NOT use this to disable the SIM card at the network level — use `change_sim_status` for that. Always call `get_subscriber` first to confirm current status before modifying. |
| change_sim_status | Use this to change the physical SIM/eSIM card status at the SIM provider level, independent of the OCS subscriber lifecycle status. Statuses: ENABLED (normal operation), DISABLED (blocked at network level, subscriber cannot connect), DELETED (irrecoverably removes the SIM profile — use only to decommission). WARNING: DELETED is irreversible. Always use `dry_run=true` first. Internally resolves ICCID → numeric simId via a getSingleSubscriber call before forwarding to OCS. Params: `iccid` (subscriber identifier), `simStatus` ('ENABLED' | 'DISABLED' | 'DELETED'). Returns: updated SIM record with new status. Do NOT use this to change the subscriber's OCS lifecycle status — use `modify_subscriber_status`. Do NOT confuse DISABLED (reversible) with DELETED (irreversible). |
| get_sim_provider_status | Use this to check the physical SIM/eSIM card status at the SIM provider level (ENABLED, DISABLED, DELETED) — distinct from the OCS subscriber status. Useful when `get_subscriber` shows ACTIVE but connectivity is broken; the SIM may be DISABLED at the provider level. Internally resolves ICCID → numeric simId. Params: `iccid` (subscriber identifier). Returns: provider status object with `simStatus`, `activationDate`, `lastStatusChange`. Do NOT use this to change the SIM status — use `change_sim_status` for that. |
| get_subscriber_location | Use this to get the last known roaming location of a subscriber (country and operator). Returned on a best-effort basis — location is updated when the device re-registers on the network. Params: `iccid` (subscriber identifier). Returns: object with `country`, `countryCode`, `network`, `operator`, and `timestamp` of last update. Do NOT use this for cell-tower-level precision — use `get_subscriber_location_by_cell_id` instead. Do NOT use this for bulk fleet location analysis — use `audit_network_coverage` for that. |
| modify_subscriber_contact_info | Use this to update the contact details stored on a subscriber record in OCS. Only the fields you provide are updated — omitted fields are left unchanged. Params: `iccid` (subscriber identifier), `firstName` (optional), `lastName` (optional), `company` (optional), `email` (optional), `phoneNumber` (optional). Returns: updated subscriber contact record. Do NOT use this to change subscriber status, balance, or traffic flags — those have dedicated tools. |
| set_subscriber_traffic_restrictions | Use this to enable or disable individual traffic types for a subscriber: mobile data, voice calls (mobile-originated and mobile-terminated), and SMS. Omit any flag to leave it unchanged. Changes take effect immediately at the OCS level. Params: `iccid` (subscriber identifier), `dataAllowed` (boolean, controls data traffic), `mocAllowed` (boolean, controls outbound calls), `mtcAllowed` (boolean, controls inbound calls), `smsMoAllowed` (boolean, controls outbound SMS). Returns: updated traffic restriction record for the subscriber. Do NOT use this to throttle bandwidth — use `hlr_set_bitrate` for speed limiting. Do NOT use this to suspend the subscriber entirely — use `modify_subscriber_status` (SUSPENDED) instead. |
| modify_subscriber_steering_list | Use this to assign or remove a network steering list on a specific subscriber, controlling which mobile operators the subscriber's eSIM prefers to connect to. Steering lists are managed separately — call `list_steering_lists` to get valid IDs. This operates at the SUBSCRIBER level only. After assigning, call `push_steering_to_subscriber` to push the change to the physical device immediately; without that call the device continues using the old operator preference list until next re-registration. Params: `iccid` (subscriber identifier), `steeringListId` (integer from `list_steering_lists`, or null/0 to remove the current steering list). Returns: updated subscriber record confirming the new steeringListId. Do NOT use this for account-level steering (no MCP tool yet — gap G-03, awaiting eSIMVault input). |
| move_subscriber_range_to_account | Use this to move a contiguous ICCID range of subscribers to a different account. Useful for bulk subscriber migrations between accounts or during account restructuring. Params: `iccidFrom` (start ICCID of range, inclusive), `iccidTo` (end ICCID of range, inclusive), `accountId` (target account ID from `list_reseller_accounts`). Returns: OCS confirmation of the range move with affected subscriber count. Do NOT use this for a single subscriber move — provide identical iccidFrom and iccidTo. Always call `list_subscribers` on the range first to verify the correct subscribers are included. |
| hlr_set_bitrate | Use this to set a hard bandwidth cap for a subscriber at the HLR (Home Location Register) level. This is a network-level throttle applied regardless of package allowance — use it to enforce fair-use speed limits or to throttle heavy users without suspending service. Common values: 256000 (256 kbps throttle), 1000000 (1 Mbps), 0 (remove limit). Internally resolves ICCID → IMSI via a getSingleSubscriber lookup. Params: `iccid` (subscriber identifier), `bitrate` (integer, bits-per-second; 0 removes the limit). Returns: HLR confirmation with the applied bitrate. Do NOT use this to block data entirely — use `set_subscriber_traffic_restrictions` with `dataAllowed=false`. Do NOT use this to change throttling thresholds on a package template — use `modify_template_throttling`. |
| hlr_get_bitrate | Use this to read the current HLR-level bandwidth cap applied to a subscriber. A non-zero value means the subscriber is throttled to that speed regardless of package allowance. A zero or null response means no HLR-level cap is in effect. Internally resolves ICCID → IMSI via a getSingleSubscriber lookup. Params: `iccid` (subscriber identifier). Returns: object with `bitrate` (integer, bits-per-second) or null if no limit is set. Do NOT use this to check package data allowance limits — use `list_subscriber_packages` for that. |
| list_subscriber_packages | Use this to retrieve all prepaid packages currently assigned to a subscriber. Returns each package's allowance (data/voice/SMS), consumed usage, expiry date, status, and packageId. Always call this before any package modification tool (`modify_package_limits`, `modify_package_expiry`, `modify_package_status`, `delete_subscriber_package`) to confirm the correct packageId and current state. Params: `iccid` (subscriber identifier). Returns: array of package records with `packageId`, `name`, `status`, `dataLimit`, `dataUsed`, `expirationDate`, `recurring` flag. Do NOT use this to browse the product catalog — use `list_package_templates` for that. |
| assign_package | Use this to assign a one-time prepaid data/voice package to a subscriber from an existing template. The package is active immediately (or at first usage, depending on template settings). Params: `iccid` (subscriber identifier), `packageTemplateId` (integer from `list_package_templates`). Returns: created package record with `packageId`, `startDate`, `endDate`, and allowances. Do NOT use this for packages that should auto-renew — use `assign_recurring_package` instead. Do NOT use this to provision a new subscriber end-to-end — consider `provision_esim_wizard` for a guided flow with dry-run preview. |
| assign_recurring_package | Use this to assign an auto-renewing prepaid package to a subscriber. The package renews automatically based on the template's periodicity settings, reducing churn from manual renewal. Params: `iccid` (subscriber identifier), `packageTemplateId` (integer from `list_package_templates` — must be a template configured with recurring/periodicity settings). Returns: created recurring package record with `packageId` and renewal schedule. Do NOT use this for one-time packages — use `assign_package` instead. To pause or cancel auto-renewal without deleting the package, use `stop_resume_recurring_package`. |
| modify_package_limits | Use this to change the data, voice, or SMS allowance ceilings on an already-assigned subscriber package. Useful for mid-cycle top-ups or corrections without assigning a new package. Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), `limits` (JSON string with the limit fields to change, e.g. {"dataLimit": 5368709120}). Returns: updated package record with new limits. Do NOT use this to change the package template (affecting future subscribers) — use `modify_template_core`. Do NOT use this to change expiry — use `modify_package_expiry`. Always call `list_subscriber_packages` first to confirm the correct packageId. |
| modify_package_expiry | Use this to extend or shorten the expiry date of an active prepaid package on a subscriber. Useful when a subscriber's trip is longer than expected or for promotional extensions. Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), `expirationDate` (ISO 8601 date string, e.g. '2026-06-01' or '2026-06-01T23:59:59'). Returns: updated package record with the new expiry date. Do NOT use this to change when a package becomes active — use `modify_subscriber_package_active_period`. Do NOT use this to change data allowances — use `modify_package_limits`. |
| modify_package_status | Use this to activate or deactivate a specific prepaid package on a subscriber without removing it. A deactivated package retains its allowances and can be reactivated later. Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), `status` (new package status string, e.g. 'ACTIVE', 'INACTIVE'). Returns: updated package record with the new status. Do NOT use this to delete a package — use `delete_subscriber_package` for permanent removal. Do NOT use this to change the subscriber's overall account status — use `modify_subscriber_status`. |
| stop_resume_recurring_package | Use this to pause or restart the auto-renewal cycle of a recurring package without removing it. 'stop' halts future renewals (subscriber keeps current period until expiry); 'resume' re-enables auto-renewal from the next renewal date. Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`), `action` ('stop' | 'resume'). Returns: updated recurring package record with new renewal state. Do NOT use this to permanently delete a recurring package — use `delete_subscriber_package`. Do NOT confuse this with `modify_package_status` (which activates/deactivates a package for usage). |
| delete_subscriber_package | Use this to permanently remove a single prepaid package from a subscriber. This is irreversible — the package record and any unused allowance are deleted. Always call `list_subscriber_packages` first to confirm the correct packageId and snapshot the current state. Use `dry_run=true` on the first call. Params: `iccid` (subscriber identifier), `packageId` (integer from `list_subscriber_packages`). Returns: OCS confirmation of deletion. Do NOT use this to remove ALL packages at once — use `clean_all_packages` for that (requires separate confirm). Do NOT use this to pause a package — use `modify_package_status` to deactivate it instead. |
| clean_all_packages | DANGEROUS: Removes ALL prepaid packages from a subscriber in a single irreversible operation. There is no undo. Typical use: resetting a subscriber to zero before re-provisioning a new package series. REQUIRED workflow: (1) call `list_subscriber_packages` to snapshot what will be deleted; (2) call this tool with `dry_run=true` to preview; (3) get explicit user confirmation; (4) call again with `dry_run=false`. Params: `iccid` (subscriber identifier), `dry_run` (boolean — MUST be true on first call). Returns: list of packages that were (or would be) deleted. Do NOT use this to remove a single package — use `delete_subscriber_package` instead. |
| list_package_templates | Use this to browse the product catalog of prepaid package templates available for assignment. Returns each template's name, data/voice/SMS limits, pricing, validity period, location zone, and recurring configuration. Call this before `assign_package` or `assign_recurring_package` to obtain valid `packageTemplateId` values. Params: `accountId` (integer, optional — filter templates visible to a specific account). Returns: array of template records with `templateId`, `name`, `dataLimit`, `price`, `validityDays`, `locationZoneId`, `recurring`. Do NOT use this to list packages assigned to a specific subscriber — use `list_subscriber_packages`. |
| create_package_template | Use this to create a new prepaid package template in the product catalog. Templates define allowances, pricing, location zones, validity, and throttling thresholds that are reused each time the template is assigned to a subscriber. Params: `template` (full template configuration as a JSON string — fields include `name`, `dataLimit` in bytes, `price`, `validityDays`, `locationZoneId`, `recurring`, `throttlingActive`). Returns: created template record with the new `templateId`. Do NOT use this to modify an existing template — use `modify_template_core`. After creation, call `list_package_templates` to confirm the template is visible. |
| modify_template_core | Use this to change the core fields of an existing package template: name, data/voice/SMS limits, pricing, validity period, and location zone. Changes affect future package assignments from this template but do NOT retroactively change packages already assigned to subscribers. Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with fields to modify, e.g. {"name": "Europe 5GB", "dataLimit": 5368709120}). Returns: updated template record. Do NOT use this to modify throttling thresholds — use `modify_template_throttling`. Do NOT use this to modify recurring/renewal settings — use `modify_template_recurring`. |
| modify_template_recurring | Use this to change the auto-renewal configuration of a package template: periodicity (daily/weekly/monthly), occurrence count, and renewal trigger conditions. Changes affect future assignments and existing recurring packages assigned from this template. Params: `templateId` (integer from `list_package_templates`), `changes` (JSON string with recurring fields, e.g. {"periodicity": "monthly", "occurrences": 12}). Returns: updated template record with new recurring settings. Do NOT use this to stop an individual subscriber's recurring renewal — use `stop_resume_recurring_package`. Do NOT use this to change core template fields like data limits — use `modify_template_core`. |
| modify_template_throttling | Use this to change the bandwidth throttling thresholds on a package template. WARNING: changes apply immediately to ALL existing subscriber packages created from this template, not just future ones. Setting a lower threshold will NOT retroactively throttle subscribers already below the new threshold (the system does not re-check existing usage). Params: `templateId` (integer), `changes` (JSON string with throttling fields, e.g. {"throttlingActive": true, "firstThresholdPercent": 80, "firstThresholdLimitKbps": 1024, "errorAction": "continue_unthrottled"}). Returns: updated template record with new throttling configuration. Do NOT use this to throttle a single subscriber — use `hlr_set_bitrate` instead. Do NOT use this to change core package limits — use `modify_template_core`. |
| list_location_zones | Use this to list countries and networks within a specific location zone. WARNING: this method has a known Jackson deserialization bug in the upstream OCS API that may return malformed responses. Prefer `list_detailed_location_zones` for reliable results. Params: `locationZoneId` (integer, optional — filter to a specific zone). Returns: array of zone element records with country and operator entries. Do NOT use this for reliable zone data — use `list_detailed_location_zones` instead. Do NOT use this to create zones — use `create_location_zone`. |
| list_detailed_location_zones | Use this as the preferred way to list location zones with full detail: included countries, operator networks, zone IDs, and names. This is the working alternative to `list_location_zones` which has a known upstream deserialization bug. Use `locationZoneId` values from this response when creating or editing package templates. Params: `resellerId` (integer, optional — omit to use the token owner's reseller). Returns: array of zone objects each containing `locationZoneId`, `name`, `countries`, and `operators`. Do NOT use `list_location_zones` when you need reliable data — always use this tool instead. |
| list_destination_prefixes | Use this to list the phone number prefixes (country dialling codes) within a specific named destination list. Destination lists control which countries a subscriber may call on voice/SMS packages. You must already know the `destinationListId` to use this tool. Params: `destinationListId` (integer, optional — omit to list all known prefixes). Returns: array of prefix records with country code and E.164 prefix. Do NOT use this to discover the destination list catalog — use `list_destination_lists` for that. For data-only eSIM products without MOC voice, destination lists are irrelevant. |
| create_location_zone | Use this to create a new location zone — a named collection of countries and operators that defines where a package can be used. Location zones are required when creating package templates. Use `list_network_profiles` to find valid operator identifiers to include. Params: `zone` (full zone configuration as a JSON string — fields include `name`, `countries` (array of ISO country codes), `operators` (array of MCC-MNC strings)). Returns: created zone record with the new `locationZoneId`. Do NOT use this to modify an existing zone — no edit tool exists yet (gap G-19, pending eSIMVault). After creation, verify with `list_detailed_location_zones`. |
| subscriber_usage | Use this to retrieve daily data, voice, and SMS usage for a subscriber over a date range. Hard limit: maximum 7 days per query — do not exceed or OCS will return an error. Params: `iccid` (subscriber identifier), `startDate` (YYYY-MM-DD, inclusive), `endDate` (YYYY-MM-DD, inclusive, max 7 days from start). Returns: array of daily usage records with `date`, `dataBytes`, `voiceSeconds`, `smsCount`. Do NOT use this for event-level network activity — use `subscriber_network_events` for attach/detach events. Do NOT use this to check current package allowances — use `list_subscriber_packages`. |
| subscriber_network_events | Use this to retrieve timestamped network events for a subscriber: attach, detach, location updates, and handovers between operators. Useful for connectivity troubleshooting, roaming activity verification, and fraud pattern detection. Max 7 days per query. Params: `iccid` (subscriber identifier), `startDate` (YYYY-MM-DD, inclusive), `endDate` (YYYY-MM-DD, inclusive, max 7 days from start). Returns: array of event records with `timestamp`, `eventType`, `country`, `operator`, `mccMnc`. Do NOT use this for daily usage volumes — use `subscriber_usage` for data/voice/SMS byte counts. For real-time events (last 24h), prefer `list_recent_ocs_events` which reads from the ring buffer. |
| subscriber_active_period | Use this to retrieve the lifetime activity window for a subscriber: the date of first usage and the date of last usage. Useful for churn analysis, dormancy detection, and subscriber lifetime value calculations. Params: `iccid` (subscriber identifier). Returns: object with `firstUseDate` and `lastUseDate` (ISO 8601 strings). Do NOT use this to check current package status — use `list_subscriber_packages`. Do NOT use this for detailed daily usage patterns — use `subscriber_usage`. |
| get_tariff | Use this to retrieve the complete tariff table for a reseller: per-country, per-traffic-type (data/voice/SMS) wholesale rates. Useful for cost analysis, margin calculations, and identifying expensive roaming countries before steering decisions. Params: `resellerId` (integer, optional — omit to use the token owner's reseller). Returns: array of tariff rules, each with `country`, `trafficType`, `rate`, and `currency`. Response key in OCS is `listTariffRule`. Do NOT use this to assign a pricing plan to a subscriber — use `modify_subscriber_mobile_plan`. This shows the RESELLER's wholesale cost, not what end-users are charged. |
| send_sms | Use this to send a mobile-terminated (MT) SMS to a subscriber. Useful for service notifications, package expiry alerts, and support messages sent programmatically from the platform. Internally resolves ICCID → IMSI via a getSingleSubscriber lookup before forwarding to OCS. Params: `iccid` (subscriber identifier), `msisdn` (E.164 phone number of the subscriber), `message` (SMS text content, max 160 chars for single SMS), `sender` (optional sender ID or phone number displayed on the device). Returns: OCS delivery confirmation. Do NOT use this for bulk SMS campaigns — this sends one message per call and is rate-limited. Requires admin scope. |
| list_network_profiles | Use this to list all network profiles available to this reseller. A network profile defines the roaming configuration and operator partnerships for eSIM provisioning. Use profile IDs when creating location zones or configuring steering lists. Params: none. Returns: array of profile records with `profileId`, `name`, and coverage metadata. Do NOT use this to list operator steering configurations — use `list_steering_lists` for that. |
| diagnose_subscriber | Smart diagnostic that chains multiple API calls to analyse why a subscriber may be offline, throttled, or having connectivity issues. |
| fleet_health | Aggregates eSIM status counts, low-balance accounts, and provides a fleet-wide health summary in a single call. |
| detect_usage_anomalies | Analyses recent usage to detect anomalies: spikes, off-hours activity, or consumption exhausting the package before expiry. |
| optimize_package | Compares a subscriber's usage against their current package and all available templates; recommends better-fit packages. |
| churn_risk | Analyses usage trends, package status, balance, and activity to produce a churn risk score (0-100) with retention recommendations. |
| audit_network_coverage | Analyses which networks subscribers connect to vs steering lists; flags expensive/non-preferred network roaming. |
| marketing_intelligence | Identifies high-growth markets, underserved regions, and revenue concentration. Answers 'where should I target marketing?' |
| high_cost_subscribers | Identifies subscribers with disproportionately high data consumption relative to package value. |
| affect_subscriber_phone_number | Use this to assign a phone number (MSISDN) to a subscriber. Supports both fake/test MSISDNs and real production MSISDNs via the `phone_type` parameter. Required for MSISDN assignment workflows before activating voice services. Params: `iccid` (subscriber identifier), `phone_number` (E.164 format, e.g. +31612345678), `phone_type` ('fake' for test/dev, 'real' for production). Returns: updated subscriber record with the new MSISDN. Do NOT use this to check a subscriber's current MSISDN — use `get_subscriber` instead. |
| get_subscriber_location_by_cell_id | Use this to retrieve a subscriber's current location with cell-tower-level precision (MCC, MNC, LAC, Cell ID). More precise than `get_subscriber_location` which returns country/network only. Useful for fraud detection, roaming cost attribution, and fine-grained network troubleshooting. Params: `iccid` (subscriber identifier). Returns: object containing `mcc` (mobile country code), `mnc` (mobile network code), `lac` (location area code), `cellId`, `country`, and `operator`. Do NOT use this for bulk location mapping — it incurs one OCS call per subscriber; use `audit_network_coverage` for fleet-level location analysis instead. |
| list_destination_lists | Use this to retrieve the full catalog of destination lists available to this reseller. A destination list is a named set of phone number prefixes (country codes) that control which numbers a subscriber may call on a voice/SMS package. Returns: array of destination list records, each with `id`, `name`, and prefix count. Do NOT use this to read the prefixes inside a specific list — use `list_destination_prefixes` with a known `destinationListId` for that. Do NOT use this for data-only eSIM products without MOC voice; destination lists only apply to packages with voice/SMS allowances. |
| modify_subscriber_mobile_plan | Use this to change the mobile pricing plan assigned to a specific subscriber. The mobile plan determines per-country rates for data, voice, and SMS. Changing the plan takes effect immediately on the next OCS rating cycle. Params: `iccid` (subscriber identifier), `mobile_plan_id` (integer plan ID — obtain valid plan IDs from the OCS reseller settings or `get_tariff`). Returns: updated subscriber record confirming the new plan assignment. Do NOT use this to change package allowances — use `modify_package_limits` for that. Do NOT use this to change account-level pricing — this only affects the individual subscriber. |
| modify_subscriber_package_active_period | Use this to change the start and/or end date of a prepaid package's active period for a specific subscriber. This controls WHEN the package runs, not what it contains. Useful for scheduling packages in advance (e.g. activate on arrival date) or extending a package that would otherwise expire while the subscriber is still travelling. Params: `iccid` (subscriber identifier), `package_id` (from `list_subscriber_packages`), `start_date` (ISO 8601 date, optional), `end_date` (ISO 8601 date, optional). Returns: updated package record with new active period. Do NOT use this to change a package's data/voice allowance — use `modify_package_limits`. Do NOT use this to change the expiry date of a package — use `modify_package_expiry`. |
| modify_subscriber_voip_plan | Use this to change the VoIP pricing plan assigned to a specific subscriber. VoIP plans control billing rates for VoIP calls made through the OCS platform, separate from the standard mobile plan's call rates. Params: `iccid` (subscriber identifier), `voip_plan_id` (integer VoIP plan ID from the OCS reseller settings). Returns: updated subscriber record confirming the new VoIP plan. Do NOT use this for mobile (non-VoIP) plan changes — use `modify_subscriber_mobile_plan`. For data-only eSIM products without VoIP services this tool has no effect. |
| push_steering_to_subscriber | Use this AFTER `modify_subscriber_steering_list` to actively push the updated OPLMN (operator preference list) to the subscriber's physical eSIM/SIM. Without this call, the steering list assignment change is recorded in OCS but the device continues using the old operator preference list until it performs a network re-registration. This is required for immediate operator switching (e.g. steering a subscriber away from an expensive roaming partner in real time). Params: `iccid` (subscriber identifier). Returns: push confirmation from OCS with delivery status. Do NOT call this without first calling `modify_subscriber_steering_list` — pushing without an assigned steering list is a no-op and wastes an OCS call. |
| reset_subscriber_gz_counter | ADMIN: Use this to reset the Gz (Diameter accounting) usage counter for a subscriber. Typically used after a billing dispute or test-cycle reset where accumulated usage data must be cleared. This operation is IRREVERSIBLE — the usage history for the current counter period is permanently zeroed. Params: `iccid` (subscriber identifier). Returns: OCS confirmation of the counter reset. Always call `subscriber_usage` first to capture the usage snapshot before resetting. Do NOT use this to pause data usage — use `set_subscriber_traffic_restrictions` with `dataAllowed=false` instead. |
| carrier_ask | Use this when you want to perform a carrier operation but don't know which specific tool to call. Describe your intent in plain language and carrier_ask will identify the correct tool(s) and suggest the required parameters. For simple read intents, it executes directly and returns results. For destructive operations it returns a confirm_token that you must pass in a second call. Params: `intent` (string — natural language description of what you want to do, e.g. 'throttle ICCID 8932... to 256kbps' or 'show me Mango fleet usage this week'), `context` (optional object with `iccid`, `account_id`, `reseller_id` if already known). Returns: RouteResult — one of: confirmed (read op executed), pending_confirm (destructive, returns confirm_token), ambiguous (clarifying question), none (no match). Do NOT use this as a substitute for calling tools directly when you know the right tool — direct tool calls are faster and cheaper. Use carrier_ask only for ambiguous or exploratory intents. STATUS: scaffold — routing engine not yet active (follow-up PR). Currently echoes intent back. |