@carrierllc/mcp

Natural language control of your MVNO/eSIM fleet. 43 OCS tools + 9 intelligence composites + 5 prompts. Direct stdio mode — no OAuth required.

Durable inventory issuance

assign_package with account_for_subs (or no ICCID) calls the authenticated Carrier API's /v1/subscribers/issue-from-inventory route. Supply a stable request_key: 1–200 characters, first character alphanumeric, remaining characters alphanumeric, _, ., :, or -. No key is generated. Optional business_reference identifies an existing storefront order; the API must authorize it, it is not proof of ownership.

Set CARRIER_API_TOKEN to your own Carrier credential. Hosted MCP and carrier packages assign --account-id … --template-id … --request-key … --commit forward the current authenticated session credential. Explicit ICCID assignment remains the scoped OCS subscriber path, mutually exclusive with inventory/business reference.

Unknown response/transport outcomes preserve request_key and never trigger an automatic second dispatch. Reconcile using the same key; do not mint a replacement. Dry-run validates without allocating or resolving credentials.

Quick start

Interactive CLI (non-developers)

npx -y -p @carrierllc/mcp carrier-mcp
# opens the Carrier TUI: status, sign-up/sign-in, install MCP, fleet NL examples

carrier status          # plugin + MCP + next steps
carrier plugin install  # zero-cred MCP URL; OAuth on first use in Claude
carrier open signup     # create account
carrier examples        # paste-ready “talk to fleet” prompts
carrier login               # browser once; native OAuth refreshes silently
carrier ask "fleet health"   # uses CLI OAuth / compatible Claude Code OAuth / explicit key
carrier exec -- bash        # real child terminal with CARRIER_API_KEY in its environment

Entry A: register https://mcp.carrier.llc/mcp with no token. The first tool call in Claude/Cursor opens Clerk OAuth (Google / GitHub / email).

Natural-language answers

carrier ask "how many subscribers are there?" and the interactive home's Ask the fleet action present executed tool results as readable answers. Known OCS list summaries use the server's authoritative summary.total, not a recount of the displayed rows. That number describes the result/page, not necessarily the entire fleet; paging, missing rows and shortened display are reported explicitly. Nested subscriber status and SIM inventory status remain separate. A server facet that could not read nested status is not a claim that subscriber status is missing.

This is deterministic presentation, not another AI/model call. The original question distinguishes counts from requested lists/status/details. Unsupported predictions and judgements receive an explicit limitation rather than unrelated records. Current subscriber status uses the shared OCS open-period normalizer, with its maintained closed-history fallback; SIM inventory remains separate.

Default JSON presentation uses typed scalar allowlists and explicit shallow account/result wrappers. Unknown fields, nested shapes, and wrong field types are omitted with a safe limitation; they are never recursively dumped. Safe ordinary scalar facts remain readable. Empty or unsupported summary facets are omitted. Plain-text tool answers are passed through, shortened only at whole sentence/row boundaries; this is not a general redaction guarantee for arbitrary prose. Oversized indivisible rows are omitted entirely with the raw-output hint.

carrier ask "how many subscribers are there?" --json

--json is explicit raw access: complete JSON stdout, no banner/spinner; plain text is encoded as a JSON string. Raw output may contain sensitive data. Failures remain nonzero with errors on stderr. The MCP machine contract and domain commands are unchanged. Ambiguous intents and confirmation-required mutations still do not execute a resolved tool.

OAuth and terminal handoff

Carrier commands, status and Ask the Fleet share credential resolution. Explicit CARRIER_API_KEY / CARRIER_ORG_API_KEY always win. Native carrier login stores a private refreshable session with one cross-process owner lock and atomic writes. Login, refresh and logout serialize; a completed logout cannot be resurrected by an earlier refresh. A crashed CLI owner leaves a fail-closed credentials.lock directory: verify that no CLI login/refresh is running before manually removing that directory. Changing the callback port triggers fresh client registration. Native login and refresh request the exact production MCP resource. A present wrong/malformed token-response resource is rejected before credential storage; legacy absence is distinct and refresh retains a previously known binding.

Existing bash/zsh terminal (explicit setup)

source "$(carrier shell-path bash)" # use zsh instead of bash in zsh
carrier_auth_export
# CARRIER_API_KEY is now exported in THIS shell and its subsequent children.
# Before an arbitrary headless job, refresh this snapshot again:
carrier_auth_export && your-headless-job
carrier logout
carrier_auth_clear                 # erase this shell's snapshot too

Only a shipped static file is sourced. No secret is printed, evaluated as code, put in command arguments/history, or written to a startup file. The function reads an anonymous private pipe via an inherited descriptor. It refuses shell traps and turns off xtrace/verbose without restoring them, because the next caller command could expand the newly exported environment. Bash opt-in loading enables errtrace so caller ERR traps are visible for refusal. Trusted commands, same-UID process environment readers and crash dumps can still expose a bearer; this is not protection from a compromised shell/OS. Do not re-enable tracing around credentials.

Shell acceptance requires both bash and zsh: pnpm test:oauth-shell. CARRIER_TEST_ZSH may point to an isolated zsh binary and CARRIER_TEST_ZSH_MODULE_PATH to its matching modules. The general repair suite reports a missing zsh interpreter as an explicit SKIP, never a zsh pass; the acceptance command fails when either interpreter is unavailable.

OAuth exports carry CARRIER_OAUTH_ORIGIN, CARRIER_OAUTH_EXPIRES_AT (epoch ms) and a CARRIER_OAUTH_HANDOFF fingerprint plus non-secret CARRIER_OAUTH_BINDING. Carrier invocations reread only the selected owner, source directory/file, server, registration and opaque subject/grant. Same-owner token rotation is allowed; expiry, logout, owner/config/account/org changes fail closed, never switch to another valid client session. Old exports without binding must be exported again. These metadata equality checks are not cryptographic account/org proof. Arbitrary programs retain it until expiry: re-run carrier_auth_export before consumption. Replacing CARRIER_API_KEY intentionally overrides the fingerprint and remains authoritative. carrier_auth_clear removes this shell's exported key and metadata, not the other client's login.

carrier exec -- <command> [args...] remains available for a trusted child only; no setup required, no parent-shell mutation, and child exit/signal is preserved. OAuth is a short-lived bearer, not an ak_ key.

Supported read-only MCP owners

Without a native session, a current compatible MCP access token may be reused; no refresh grant is copied, rotated or written by Carrier. If the owner expires, refresh it in that client or use native carrier login. No owner reauth command is invoked. Multiple current owners require CARRIER_MCP_OAUTH_OWNER=hermes or claude; the CLI never guesses which account to use.

• Claude Code 2.1.277 and 2.1.296: exact inspected config and storage adapters. The owner's .claude.json lives under CLAUDE_CONFIG_DIR || ~; an existing legacy .config.json takes precedence. For the consuming CLI's cwd, local projects[real git root || real cwd].mcpServers wins over approved ancestor .mcp.json project config, which wins over user config. Other projects are not candidates. Project import supports explicit trusted user settings approval only; pending/rejected or ambiguous policy/settings fail closed. Hashes the actual {type,url,headers:headers||{}} in original insertion order: HTTP, SSE and absent type remain distinct. No hardcoded empty-header hash. Managed selection remains unsupported and fails closed; no inferred plugin/proxy/CLI override resolution. Authorization/API-key/cookie headers and unresolved environment substitutions are not imported as OAuth. CLAUDE_SECURESTORAGE_CONFIG_DIR takes precedence by presence for credential storage; present-empty selects ~/.claude, while nonempty and CLAUDE_CONFIG_DIR retain the exact NFC strings (no trim or resolve before the Keychain hash). USER || os.userInfo().username selects the exact account, with Claude's invalid-account fallback. An approved custom OAuth environment selects only its own suffix; unrelated suffixes/accounts are never enumerated. Linux reads the private .credentials.json. CARRIER_MCP_OAUTH_FILE explicitly selects that file backend on either platform, without consulting Keychain. CamelCase expiry is epoch milliseconds.
• Hermes: selected HERMES_HOME (default ~/.hermes), exact configured mcp_servers.carrier.url, with private mcp-tokens/carrier.json, .client.json and .meta.json. Real snake_case access-token fields, hermes_issuer, Bearer type and absolute expires_at in seconds are required. Issuer/discovery endpoints, client registration and resource configuration are checked. Legacy relative-only expiry is refused. Config JSON and simple scalar block YAML are supported; nested/alias/flow constructs fail closed.

CARRIER_MCP_OAUTH_SERVER selects an alternative explicit name. Private mode and current-user file ownership, exact issuer/resource, read scope and finite future expiry are required. CARRIER_OAUTH_ACCOUNT optionally selects the Carrier opaque token's user prefix; it is not cryptographic account/org proof. Only the server validates actual token audience, organization and grant permissions. Invalid native state never falls through to another owner.

On macOS the packaged native/claude-keychain.js uses the built-in JXA Objective-C bridge and Apple Security Framework: one generic-password query, exact service and account, kSecMatchLimitOne, kSecReturnData, kSecUseAuthenticationUIFail, plus process-local legacy UI inhibition. There is no compiler/download/install-at-login dependency, no security -w, no broad dump, and no owner lock/refresh/login. Only non-secret selectors reach stdin. Only the selected access-token fields reach an inherited private FD; stdout/stderr are discarded. Owner refresh grants, client secrets and unrelated credentials never leave the helper. Apple may report an ACL prompt requirement or locked store identically (errSecInteractionNotAllowed): locked denotes that noninteractive refusal, not a diagnosis of the physical Keychain state. errSecAuthFailed/user-cancel are denied, parse errors are malformed, and other failures are unavailable. None falls back to plaintext or Hermes. Only errSecItemNotFound for the exact item permits Claude's documented private file fallback. An existing item without the exact MCP entry does not fall back. Keychain reuse requires claude --version to be exactly 2.1.277 or 2.1.296; other versions fail closed. Compatibility is an explicit inspected allowlist, not a version range. The source contracts are tested on Linux; a real Darwin absent-item probe also executes the packaged helper byte-for-byte without stdout/stderr. Successful existing-item access and installed end-to-end Mac OAuth remain unproved. The inspected Mac 2.1.296 query returned denied (OSStatus -25293), not absence; this adapter never broadens Keychain access or falls back after that refusal. Claude Desktop, Cursor, Windsurf and mcp-remote remain unsupported owners. Issuer-less entries are intentionally rejected. carrier logout disables MCP reuse until a successful native login and never edits the owner's store or another shell's explicit keys.

Native API references: Apple SecItemCopyMatching, Apple SecItem.h, Apple JXA release notes, Claude authentication storage.

Domain commands

With a headless key in the environment, each capability has its own command, grouped by the same domains the console uses: subscribers, packages, templates, zones, steering, intelligence.

carrier subscribers list --account-id 1170
carrier subscribers usage --iccid 8944… --json     # last 7 days by default
carrier packages list --iccid 8944…
carrier intelligence fleet-health
carrier steering assign --iccid 8944… --list-id 12 --commit

carrier <domain> --help lists the verbs, carrier <domain> <verb> --help the flags. Two rules apply everywhere:

• --json prints the raw tool response on stdout and nothing else, so it pipes into jq.
• Commands that change something preview as a dry run. Add --commit to apply.

Stdio server (token env)

ESIMVAULT_API_TOKEN=your_key npx -y -p @carrierllc/mcp carrier-mcp

Get a key at mcp.carrier.llc or an org API key from the console.

Install in Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "carrier": {
      "command": "npx",
      "args": ["-y", "-p", "@carrierllc/mcp", "carrier-mcp"],
      "env": {
        "ESIMVAULT_API_TOKEN": "YOUR_KEY"
      }
    }
  }
}

Install in Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "carrier": {
      "command": "npx",
      "args": ["-y", "-p", "@carrierllc/mcp", "carrier-mcp"],
      "env": {
        "ESIMVAULT_API_TOKEN": "YOUR_KEY"
      }
    }
  }
}

Install in Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "carrier": {
      "command": "npx",
      "args": ["-y", "-p", "@carrierllc/mcp", "carrier-mcp"],
      "env": {
        "ESIMVAULT_API_TOKEN": "YOUR_KEY"
      }
    }
  }
}

Remote HTTP (OAuth 2.1)

For multi-user deployments with OAuth 2.1 + PKCE, use the remote endpoint:

{
  "mcpServers": {
    "carrier": {
      "type": "http",
      "url": "https://mcp.carrier.llc/mcp"
    }
  }
}

Environment variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | CARRIER_API_TOKEN | Inventory issuance | — | Your own authenticated Carrier API credential. Required for durable assign_package inventory; never falls back to an OCS token. | | CARRIER_API_BASE_URL | No | https://api.carrier.llc | Carrier REST API origin for durable inventory. Do not use the OCS provider URL. | | ESIMVAULT_API_TOKEN | Explicit OCS tools | — | Your eSIMVault OCS API token; not a Carrier API credential | | CARRIER_OCS_API_TOKEN | Alternative | — | Alias for ESIMVAULT_API_TOKEN | | CARRIER_OCS_BASE_URL | No | https://ocs.esimvault.cloud | OCS base URL (no trailing slash) | | BROWSER_USE_API_KEY | No | — | Browser Use Cloud key. Enables the browsing agent (ui_agent_ask). Runs are billed to this key at roughly $0.20–1.00 each | | CARRIER_BROWSER_USE_MAX_RUNS | No | 10 | Browser-agent runs allowed per CLI process. 0 disables the agent. See the caveats below | | CARRIER_ALLOW_PORTAL_PASSWORD | No | unset | Set to 1 to allow the ten OCS-dashboard tools to use a portal login from this machine. See below | | CARRIER_OCS_PORTAL_USERNAME | No | — | OCS portal username. Only used when the flag above is set | | CARRIER_OCS_PORTAL_PASSWORD | No | — | OCS portal password. Only used when the flag above is set | | CARRIER_OCS_DASHBOARD_URL | No | https://ocs.esimvault.cloud | Dashboard the portal agent logs into | | GREENZONE_PORTAL_URL | No | — | Portal host for the greenzone_whitelist_* tools. Wins over the two below | | CARRIER_OCS_PORTAL_URL | No | — | Reseller portal host. Used by Greenzone when GREENZONE_PORTAL_URL is unset | | OCS_DASHBOARD_URL | No | https://portal-esimvault.cloud | Portal host Greenzone falls back to. CARRIER_OCS_BASE_URL is never used for the portal |

The browser agent costs real money

ui_agent_ask and the OCS-dashboard tools dispatch a hosted browser agent. Each run costs roughly $0.20–1.00, billed to your own BROWSER_USE_API_KEY.

CARRIER_BROWSER_USE_MAX_RUNS caps how many runs one CLI process may start. Read what it does not do:

• It caps runs, not dollars. The vendor prices a run after it finishes.
• It does not survive a restart. Each new CLI process starts a fresh count, so a caller that respawns the CLI between runs is not bounded by it.

The only hard financial ceiling is a spend limit set in your Browser Use account. Set one.

Opting in to the OCS portal password

Ten ui_* tools — steering lists, sub-account creation, destination lists, package-template deletion, location-zone edits — have no OCS REST equivalent. They work by driving the OCS web dashboard, which means logging into it. By default the CLI has no portal login and these tools refuse.

You can supply one. Understand what you are supplying first:

• This is a portal password, not a scoped API token. It grants full dashboard access to anyone who holds it. CARRIER_OCS_API_TOKEN is a different kind of secret and is not a precedent for this.
• An environment variable is a poor place for one. It is readable from shell history, from ps output by any process on the machine, and from CI logs.
• It is sent to Browser Use Cloud, which types it into the OCS login form.

Carrier never logs it, never returns it in tool output, and never writes it to an audit row — but the exposure above is yours to accept.

Two independent things must both be true, and neither alone does anything:

export CARRIER_ALLOW_PORTAL_PASSWORD=1
export CARRIER_OCS_PORTAL_USERNAME='...'
export CARRIER_OCS_PORTAL_PASSWORD='...'

With the flag set, the CLI prints the warning to stderr at startup. Without both halves, the ten tools return the same "requires the remote Worker" refusal they returned before this option existed.

Every one of the ten accepts dry_run: true, which returns the agent prompt with the credentials redacted and dispatches nothing. Use it first.

ui_request_reseller_relay_change is not one of the ten and is never gated: it drafts text and touches no portal.

Tools (52 total)

Reseller (6)

| Tool | Scope | Description | |------|-------|-------------| | list_reseller_accounts | read | List all accounts across all resellers | | get_reseller_info | read | Retrieve reseller details | | esim_status_per_account | read | eSIM status breakdown per account | | list_sponsors | read | List all sponsor networks | | list_steering_lists | read | List all network steering lists | | modify_account_balance | write | Adjust or set reseller account balance |

Subscriber (13)

| Tool | Scope | Description | |------|-------|-------------| | get_subscriber | read | Get full subscriber details by ICCID or MSISDN | | list_subscribers | read | List subscribers with optional filters | | get_sim_provider_status | read | Check SIM provider-level status | | get_subscriber_location | read | Get last known subscriber location | | hlr_get_bitrate | read | Get HLR bitrate for a subscriber | | modify_subscriber_balance | write | Adjust or set subscriber balance | | modify_subscriber_status | write | Change subscriber OCS status | | change_sim_status | write | Change SIM status at provider level | | modify_subscriber_contact_info | write | Update subscriber contact info | | set_subscriber_traffic_restrictions | write | Configure traffic restrictions | | modify_subscriber_steering_list | write | Change network steering list for a subscriber | | hlr_set_bitrate | write | Set HLR bitrate for a subscriber | | move_subscriber_range_to_account | write | Move subscriber range to another account |

Packages (9)

| Tool | Scope | Description | |------|-------|-------------| | list_subscriber_packages | read | List all prepaid packages for a subscriber | | list_package_templates | read | List all prepaid package templates | | assign_package | write | Assign package template to subscriber | | assign_recurring_package | write | Assign recurring package to subscriber | | modify_package_limits | write | Change data/voice/SMS limits on active package | | modify_package_expiry | write | Change expiration date of active package | | modify_package_status | write | Activate or deactivate a subscriber package | | stop_resume_recurring_package | write | Stop or resume recurring package auto-renewal | | delete_subscriber_package | write | Remove a package from a subscriber |

Templates & Zones (7)

| Tool | Scope | Description | |------|-------|-------------| | clean_all_packages | write | Remove ALL packages from a subscriber | | create_package_template | write | Create a new prepaid package template | | modify_template_core | write | Modify core settings of a package template | | modify_template_recurring | write | Modify recurring settings of a package template | | modify_template_throttling | write | Modify throttling settings of a package template | | list_location_zones | read | List countries/networks in a location zone | | list_detailed_location_zones | read | Get detailed location zone definitions |

Statistics & Misc (8)

| Tool | Scope | Description | |------|-------|-------------| | subscriber_usage | read | Get daily usage for a subscriber (max 7 days) | | subscriber_network_events | read | Get network events for a subscriber (max 7 days) | | subscriber_active_period | read | Get subscriber active period | | get_tariff | read | Retrieve customer tariff/pricing table | | list_destination_prefixes | read | List phone number prefixes in destination lists | | list_network_profiles | read | List all available network profiles | | create_location_zone | write | Create a new location zone | | send_sms | write | Send MT SMS to a subscriber |

Intelligence (9)

AI composites that chain multiple OCS calls to produce structured insights:

| Tool | Description | |------|-------------| | diagnose_subscriber | Chains 5+ OCS calls to diagnose connectivity issues | | fleet_health | Single-call fleet overview: accounts, eSIM counts, low-balance alerts | | detect_usage_anomalies | Detect abnormal usage patterns and burn-rate risks | | optimize_package | Match subscriber usage to the best available package | | churn_risk | Score churn risk (0-100) with retention recommendations | | audit_network_coverage | Audit network coverage and steering effectiveness | | marketing_intelligence | Market segmentation and upsell opportunities | | high_cost_subscribers | Identify highest-cost subscribers for margin optimization | | detect_country_entry | Resolve the current country from the last MCC and compare it to an expected country |

Prompts (5)

| Prompt | Args | Description | |--------|------|-------------| | fleet_health_report | — | Full fleet health overview | | subscriber_deep_dive | iccid | Deep diagnostic for a single subscriber | | revenue_optimization | — | Revenue analysis and upsell opportunities | | coverage_analysis | — | Network coverage audit and steering recommendations | | bulk_operations_planner | operation | Plan and dry-run a bulk fleet operation |

Destructive tools and dry_run

All write/admin tools accept an optional dry_run: true argument. When set, the tool returns the would-be request without calling OCS — safe for previewing operations.

"Suspend ICCID 8988... but check what it would do first (dry_run)"

Links

• Product page: mcp.carrier.llc
• Package: npmjs.com/package/@carrierllc/mcp
• OCS docs: docs.esimvault.cloud/ocs-api

MIT License. Copyright 2025 Lifecycle Innovations Limited.