esimba.ai MCP Server Documentation

E-mail: sales@esimba.aiUpdated: 26 October 2026

Introduction

Connect your AI assistant to your esimba partner account and work with it in plain language: check the balance, browse bundles, order eSIMs, watch usage, top up lines, manage auto-refill.

The assistant sees and changes only your own account, and asks you before anything that costs money.

Server address

https://myaccount.keepgo.com/mcp/partner

Webstore partners

https://myaccount.<your partner portal domain>/mcp/partner

Before you start

A partner (reseller or distributor) account on your brand's partner portal.
Your API credentials: the API key and the access token from the API Credentials section of your partner account. You type them once, on the sign-in page; the assistant never gets them.
An assistant that supports remote MCP servers with OAuth: Claude Desktop or claude.ai, Claude Code, Cursor or VS Code.
The server address: https://myaccount.keepgo.com/mcp/partner. Webstore partners use the domain of their own partner portal instead: https://myaccount.<your partner portal domain>/mcp/partner. An account signs in only on its own brand's address.

Where to find your credentials

Partner account
 └ API Credentials
    ├ API key
    └ Access token

Connect your assistant

You only give the assistant the address. On first use it opens a browser page where you sign in.

Claude Desktop / claude.ai

Open Settings → Connectors → Add custom connector.
Paste the server address, leave the other fields empty, save.
Click Connect and sign in on the page that opens.

Claude Code

Add the server with the command in the code panel. Then run /mcp in Claude Code, pick esimba and choose Authenticate.

Cursor

Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

VS Code

Add the server to .vscode/mcp.json.

In Cursor and VS Code, start the server and follow the sign-in prompt.

Claude Code

claude mcp add --transport http esimba \
  https://myaccount.keepgo.com/mcp/partner

Cursor: ~/.cursor/mcp.json

{
  "mcpServers": {
    "esimba": {
      "url": "https://myaccount.keepgo.com/mcp/partner"
    }
  }
}

VS Code: .vscode/mcp.json

{
  "servers": {
    "esimba": {
      "type": "http",
      "url": "https://myaccount.keepgo.com/mcp/partner"
    }
  }
}

Sign in and permissions

The sign-in page shows your brand. Enter your API key and access token and tick what the assistant may do. Only read is ticked by default; permissions the assistant asked for are marked “requested by the assistant”. To change permissions later, reconnect the server and tick again.

Permission	What it allows
`read`	See your balance, catalogue and prices, coverage, lines, usage, transactions, orders and billing protection. Always on.
`order`	Order new eSIMs. Charges your balance.
`manage`	Top up lines, add plans, auto-refill, deactivation date, block and restore, line notes. Top-ups and auto-refill charge your balance.
`install`	See activation codes (LPA), QR codes, PIN and PUK. Anyone with an activation code can install the eSIM, so tick it only if the assistant must hand them out.
`destructive`	Request refunds.
`messaging`	See the phone number of a line.
`support`	Search the partner help center; usage simulation on the sandbox server.

Without install, activation codes, QR, PIN and PUK show as “withheld” everywhere, including in the answer to a new order.

Default permissions at sign-in

[x] read        always on
[ ] order       charges your balance
[ ] manage      top-ups charge your balance
[ ] install     activation codes, QR, PIN, PUK
[ ] destructive refunds
[ ] messaging   phone number of a line
[ ] support     help center, sandbox

What the assistant can do

The current tools, by the permission they need, are listed in the code panel.

The tool set may change without notice: tools may be added, renamed or removed, and their arguments may change. If you build your own integration on this server, take the tools and their arguments from tools/list every time you connect; never hard-code names. For a stable integration use the esimba.ai API directly.

Some tools exist only where they apply: search_help_center only for brands with a partner help center, simulate_usage only on the sandbox server, set_deactivation_date only for travel lines.

Tools by permission

read
  get_account_balance
  get_billing_protection
  list_bundles · get_bundle
  list_coverage · list_esim_devices
  list_lines · get_line · get_line_usage
  list_refills · list_transactions
  get_order_status
order
  create_lines
manage
  refill_line · add_plan · set_auto_refill
  set_deactivation_date
  block_line · restore_line
  update_line_notes
install
  get_install_info
destructive
  request_refund
messaging
  get_line_number
support
  search_help_center · simulate_usage

Money and safety

The assistant asks first. Every action that charges money or changes a line needs your explicit confirmation; the assistant shows the line, the package and the price before it acts.
No double purchases on retry. Each purchase carries its own key, so repeating the same purchase is not charged again. The one exception is an unclear result, described next.
“Result unknown”. If a purchase ends with outcome_unknown (for example the connection dropped), it may or may not have gone through. The assistant checks your transactions before trying again; check them yourself if in doubt.
“Already in progress”. charge_in_progress means the same purchase is still running: wait a moment and check, don't buy again.
Only your account. The assistant works as your account and sees only your lines and transactions.
Activation codes are sensitive. An activation code installs the eSIM on any phone. They are shown only with the install permission; give them only to the person the line is for.
Only connect servers you trust. Text from other MCP servers, web pages or documents in the same chat must not decide what this server does.

Purchase outcomes

outcome_unknown
  may or may not have gone through
  → check transactions before buying again

charge_in_progress
  the same purchase is still running
  → wait and check, don't buy again

Limits

Up to 50 partner API calls a minute per account through the assistant. Your partner API limit (60 a minute) is shared with your own integration.
Every answer tells the assistant how many calls are left this minute (rate_limit_remaining). On rate_limited it waits retry_after seconds.
Per call: up to 20 lines in one order, usage of up to 10 lines at once, refunds for up to 100 lines.

Limits at a glance

calls per minute (assistant)   50
partner API limit (shared)     60
lines per order                20
lines per usage request        10
lines per refund request      100

Disconnecting

Remove the server (connector) in your assistant.
A sign-in lasts 1 hour and renews itself while you use it; after 30 days without use, or 90 days in any case, you sign in again.
Refresh API credentials in your partner account ends every assistant connection at once. It also changes the keys of your own API integration, so update it too.
To end the connections without changing your keys, ask your account manager.

Sign-in lifetime

session          1 hour, renews while in use
idle timeout     30 days
maximum          90 days

Troubleshooting

What you see	What to do
404 Not Found on the address	The address is not a partner portal, or the MCP server is not turned on for it. Use `https://myaccount.keepgo.com/mcp/partner`, or your own partner portal domain if you are a webstore partner.
“Credentials rejected” on the sign-in page	Check the API key and access token, copied without spaces. The account must be a partner (reseller or distributor) account, and you must sign in on your own brand's address.
The assistant asks you to sign in again	The sign-in expired or was ended (for example after Refresh API credentials). Sign in again.
A permission is missing (`insufficient_scope`)	Reconnect the server and tick that permission on the sign-in page.
`rate_limited`	Too many calls this minute; the assistant waits and retries.
`outcome_unknown` after a purchase	Check your transactions before buying again.
A tool is “not found”	It is not available for your brand or account type, or it has changed: the assistant should refresh its tool list.

Error codes

404                  not a partner portal
insufficient_scope   permission not ticked
rate_limited         wait retry_after seconds
outcome_unknown      check transactions
charge_in_progress   wait, don't buy again

Example requests

Ask in your own words. A few requests partners use often are in the code panel.

Requests that order or top up need the order or manage permission; the assistant shows the price and waits for your yes. A QR code needs install. Help center questions need support.

Ask your assistant

"What's my balance?"
"Which of my lines will run out of data this week?"
"Show bundles for Thailand with prices."
"Order 5 Lifetime eSIMs for Thailand."
"Top up line 8944… with 5 GB."
"Turn on auto-refill for line 8944… with 1 GB packages."
"Give me the QR code for line 8944…."
"How do I set up billing protection?"

esimba.ai MCP Server Documentation

Introduction

Before you start

Connect your assistant

Claude Desktop / claude.ai

Claude Code

Cursor

VS Code

Sign in and permissions

What the assistant can do

Money and safety

Limits

Disconnecting

Troubleshooting

Example requests

Subscribe to our newsletter