eSIMAccess MCP server

Manage the full eSIM lifecycle — browse packages, order and provision profiles, check usage, top up, and run support diagnostics — through natural language in any MCP-compatible AI client.

The Model Context Protocol (MCP) lets AI clients call external tools through a standard interface. This server turns the eSIMAccess Partner API into 16 native MCP tools — an AI-driven control centre for your eSIM business. Connect it to Claude, Cursor, Windsurf, or VS Code Copilot and run the whole lifecycle by chatting with your assistant.

What it accelerates

Deployment modes

Prerequisites

• An eSIMAccess partner account with API credentials (AccessCode + SecretKey) from the developer console.
• An MCP-compatible client — Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code Copilot.

Connect to the remote server

Point your client at the hosted endpoint:

Claude Desktop quick start

1. Open settings. Go to Settings → Connectors → Add → Add custom connector.
2. Enter details. Name: eSIMAccess · Remote MCP server URL: https://mcp.esimaccess.com/mcp. Leave Advanced settings → OAuth Client ID / Secret blank — the server registers your client automatically (dynamic client registration).
3. Connect & authorize. Click Add, then Connect. Claude opens the browser sign-in (Authorize) where you paste your AccessCode / SecretKey.

Claude Code (CLI)

claude mcp add --transport http esimaccess https://mcp.esimaccess.com/mcp

Cursor

Settings → MCP → Add new MCP server:

• Name: esimaccess
• Type: http
• URL: https://mcp.esimaccess.com/mcp

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "esimaccess": {
      "type": "http",
      "url": "https://mcp.esimaccess.com/mcp"
    }
  }
}

Verify

Ask your assistant:

The client invokes balance_query and returns your eSIMAccess balance.

Authorize (OAuth 2.1 + PKCE)

The first time a tool runs, your client has no token yet, so the server replies 401 Unauthorized and your client opens the authorization page in your browser. There:

1. Review the scopes the client is requesting (shown as chips).
2. Paste your AccessCode and SecretKey from the developer console. The server verifies them with a live signature probe, then encrypts them into the opaque tokens it returns (AES-256-GCM); from then on your credentials live only inside that token, not in any long-lived server store.
3. The client receives a short-lived bearer token (auto-refreshed). Your AccessCode / SecretKey never appear in tool arguments, URLs, or chat context.

PKCE (S256) is required, and bearer tokens must travel in the Authorization header — query-string tokens are rejected.

Scopes

Access is granted per scope; the default grant is esim:read. On the authorization page, destructive scopes are flagged in red so you see them before approving. The real guardrail is at call time, not on the consent screen: every state-changing tool (order, top-up, SMS, webhook, suspend, unsuspend, cancel, revoke) rejects the call unless its arguments carry confirm: true, so no write can happen as a side effect of a vaguely worded request.

Tools

17 tools, grouped by purpose. Each tool runs under the scope shown; the server enforces scope on every call.

Query & browse esim:read

Order & provision

Lifecycle management

Messaging & integration

Support & diagnostics

Knowledge search queries the live support knowledge base and falls back to a bundled offline copy if that service is unreachable, so the tool keeps working either way — answers may just be less current. Questions unrelated to eSIM return no results rather than a guess.

Security & multi-tenancy

• Credentials never reach the client or the model. In remote mode your AccessCode / SecretKey are encrypted (AES-256-GCM) into the opaque bearer / refresh tokens the client holds. The server keeps no long-lived copy: during the short authorization-code exchange they exist only inside an encrypted payload that is deleted the moment the code is redeemed, and that payload uses a key derived separately from the one protecting your tokens. They never appear in tool arguments, URLs, or the model's context.
• Per-tenant isolation. Your AccessCode is your tenant identity; you only ever see your own profiles, orders, and balance.
• Signed upstream calls. Every request to eSIMAccess is signed with HMAC-SHA256 using your SecretKey.
• Short-lived & revocable. Access tokens auto-refresh and can be revoked; the operator can revoke a specific token by its jti.
• Audited. Every tool call is recorded (tool, risk level, tenant AccessCode, a hashed target ICCID, and status) for the operator's audit console.

Endpoints reference

Local (stdio) mode

Prefer to keep credentials on your own machine? Run the server locally and let the client launch it via npx. Set your credentials as environment variables.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "esimaccess": {
      "command": "npx",
      "args": ["-y", "esimaccess-mcp"],
      "env": {
        "ESIM_ACCESS_CODE": "your_access_code",
        "ESIM_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "esimaccess": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "esimaccess-mcp"],
      "env": {
        "ESIM_ACCESS_CODE": "your_access_code",
        "ESIM_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

Troubleshooting

Still stuck? Ask your assistant to search the knowledge base (support_search_knowledge_base) or run support_diagnose_esim on the affected ICCID, then reach the eSIMAccess support team via the website.