---
name: issue-esim
description: Issue one Carrier eSIM with POST /v1/connectivity/intents. Use when someone wants global connectivity, a test eSIM, or test_global_1gb. Do not use the operator OCS catalog for this.
argument-hint: "[test_global_1gb|test_eu_1gb|live plan slug] [idempotency key]"
---

# Issue one eSIM

This is the developer path. It is one object, `connectivity.intent`, not the OCS method list.

The description above is the trigger. Load this skill when the task is connectivity. Do not load the operator MCP catalog first: clients inject every tool on that server before a skill can hide them.

## Install, if this skill is not already available

Once per user, so every project sees it:

```bash
npx skills add https://carrier.llc -g -a cursor -a claude-code -y
```

If that host is not published yet, install this directory:

```bash
npx skills add https://github.com/Lifecycle-Innovations-Limited/carrier.llc/tree/main/apps/mcp-stdio/plugin/carrier/skills/issue-esim -g -a cursor -a claude-code -y
```

## Issue

`POST https://api.carrier.llc/v1/connectivity/intents`

Required header: `Idempotency-Key` (stable per order, max 255 characters).

Auth: `Authorization: Bearer` with an `ak_` key from the console. Do not put the key in the repo.

```json
{ "plan": "test_global_1gb" }
```

Plans:

- `test_global_1gb` and `test_eu_1gb` succeed immediately, set `livemode` false, and never call the network. They work on the free tier. The ICCID `8900000000000000001` and SM-DP+ `test.smdp.carrier.llc` are fixtures.
- Any other slug is a live catalogue plan. It draws one eSIM from the caller's own account and needs the write scope. Do not fall back to a platform stock account.

The same key and body return the original intent. Do not issue a second SIM to "make sure".

Confirm a plan later with `POST /v1/connectivity/intents/:id/confirm` when the first call omitted `plan`.

## One-tool MCP

`carrier-intent` is a separate process with one tool, `create_connectivity_intent`. It posts the intent above. It is not registered on `https://mcp.carrier.llc/mcp`.

```json
{
  "mcpServers": {
    "carrier-intent": {
      "command": "npx",
      "args": ["-y", "-p", "@carrierllc/mcp-intent", "carrier-intent"],
      "env": { "CARRIER_API_KEY": "" }
    }
  }
}
```

Put the `ak_` key in that env block on the machine. Call the tool with `plan` and `idempotency_key`. If the package is not installed yet, use the HTTP call in the previous section.

## After it succeeds

- Read `esim.iccid` and `esim.smdp_address` back to the user.
- Webhooks: `POST /v1/connectivity/webhook_endpoints` with an https URL. The secret is shown once. Deliveries use `Carrier-Signature`.
- Test usage: `POST /v1/connectivity/usage_records` with the intent id and `quantity_mb`. A live intent refuses a self-reported quantity (`network_metered`) because the wallet meter already debits those bytes.

## If the person is new, use these sentences

A skill is a note your AI reads so it follows the same steps every time.
A plug lets an AI app press a button. This plug has one button: give this order a SIM.
This other plug opens every button a phone company uses to run many SIMs.
These are the same switchboard buttons, typed into a terminal instead of clicked. People call that a CLI.
An intent is your ask: please attach a SIM to this order. The same ask twice does not make two SIMs.
A product is the offer you sell: how much data, how many days, which countries, and the price. Saving it does not charge anyone.
A package is the data sitting on one SIM after it is issued. A code package, such as the library named @carrierllc/sdk, is a different thing.
A subscriber is one SIM line, and the person or device that line belongs to.
On this page a client is the small code library your app uses to ask for a SIM. A customer is the person who buys that SIM.
A country list is the countries someone typed on an offer. Carrier stores that list. It does not look up a live coverage map.
Steering is which mobile networks a SIM is told to join. Changing it is a job for the person who runs the SIMs.
A green zone is a short list of sites that can stay reachable after the data is used up, so someone can get help, pay, or download the SIM again.

## Do not

- Do not register `https://mcp.carrier.llc/mcp` to issue this SIM. That server is the operator fleet.
- Do not call `assign_package`, `affectPackageToSubscriber`, or another OCS write to issue this SIM.
- Do not invent coverage, fair-use, or a second network.
- Do not put a token in the repo.