Saily MCP Server

eSIM data plans for 190+ countries — browse, compare, and purchase via MCP tools.

Overview

The Saily MCP server lets AI agents browse and purchase eSIM data plans on behalf of users. It exposes MCP tools for plan discovery, checkout session management, and order completion, as well as REST endpoints for direct integration and the Machine Payment Protocol (MPP).

Key capabilities:

Search eSIM plans by country (190+ countries supported)
View pricing, data allowances, and plan durations
Create checkout sessions and complete purchases using Shared Payment Tokens (SPTs)
Direct one-step purchase flow for agents with SPT access
Machine Payment Protocol (MPP) support via POST /mcp/purchase

Authentication

The server uses OAuth 2.1 with PKCE (S256) for authentication.

Discovery Endpoints

Endpoint	Description
`GET /.well-known/oauth-protected-resource`	Protected resource metadata
`GET /.well-known/oauth-authorization-server`	Authorization server metadata
`GET /.well-known/mcp/server-card.json`	MCP server card with full tool listing

OAuth Flow

Dynamic Client Registration — POST /mcp/oauth/register to obtain a client_id.
Authorization — Redirect the user to GET /mcp/oauth/authorize with PKCE code_challenge (S256 method).
Token Exchange — Exchange the authorization code at POST /mcp/oauth/token with the code_verifier.

Scopes: mcp:read (browse plans, payment providers) and mcp:write (create checkouts, complete orders).

Quick Start (10 minutes)

Getting Started

Follow these steps to connect to the server and make your first tool call.

Connect your MCP client — Point your MCP client (e.g. Claude Desktop, an MCP SDK) at the server's streamable HTTP transport endpoint: https://mcp.saily.com/mcp. The server card at https://mcp.saily.com/.well-known/mcp/server-card.json provides full connection details.
Authenticate — Your client will be guided through the OAuth 2.1 PKCE flow automatically. Register a client, authorize, and exchange the code for a token.
Browse plans — Call the browse_plans tool with a country code:
```
{ "country": "JP" }
```
You should receive a list of eSIM plans for Japan with prices, data allowances, and durations.
Check payment providers — Call get_payment_providers with a country code to see available payment methods.
Create a checkout — Pick a plan_id from the browse results and call create_checkout:
```
{ "plan_id": "...", "country": "JP" }
```
This returns a session_id, payment_url, and network_business_profile.
Complete the purchase — Either open payment_url in a browser, or pass an SPT to complete_order.

Available Tools

browse_plans

Search eSIM data plans by destination country. Returns plans (id, name, data allowance, price, duration) and regions, which lists each regional plan's covered countries once.

Parameter	Type	Required	Description
`country`	string	Yes	Destination country as an ISO 3166-1 alpha-2 code (e.g. `JP`, `US`, `DE`)

get_payment_providers

Discover available payment providers for a country. Returns provider type, uuid, environment, and network_profile_id.

Parameter	Type	Required	Description
`country`	string	Yes	ISO 3166-1 alpha-2 country code

create_checkout

Create a checkout session. Returns session_id, payment_url, and network_business_profile for SPT scoping.

Parameter	Type	Required	Description
`plan_id`	string	Yes	Plan identifier from `browse_plans`
`country`	string	Yes	The plan's destination country: the same code passed to `browse_plans`, not the buyer's home country
`quantity`	number	No	Number of plans (default 1, max 10)
`previous_session_id`	string	No	Session ID from a previous checkout to carry forward state

complete_order

Finalize a purchase with a Shared Payment Token (SPT). Call get_payment_status after to confirm completion.

Parameter	Type	Required	Description
`session_id`	string	Yes	Session ID from `create_checkout`
`payment_token`	string	No	Shared Payment Token (SPT) scoped to Saily

get_payment_status

Check the status of a checkout session. Returns pending, processing, or completed.

Parameter	Type	Required	Description
`session_id`	string	Yes	Session ID from `create_checkout`
`wait`	boolean	No	Wait up to 30s for the session to become authenticated (default false)

purchase

Direct one-step purchase with an SPT — no checkout session needed.

Parameter	Type	Required	Description
`plan_id`	string	Yes	Plan identifier from `browse_plans`
`email`	string	Yes	Customer email address
`payment_token`	string	Yes	Shared Payment Token (SPT)
`quantity`	number	No	Number of plans (default 1)

REST Endpoints

Method	Path	Description
`GET`	`/mcp/plans?country=XX`	List eSIM plans for a country
`GET`	`/mcp/payment-providers?country=XX`	List payment providers for a country
`POST`	`/mcp/purchase`	Direct purchase (supports MPP via `WWW-Authenticate` challenge)
`POST/GET/DELETE`	`/mcp`	MCP streamable HTTP transport

Example Prompts & Expected Outcomes

Example 1

"Find eSIM plans for Japan"

Expected: The agent calls browse_plans with country: "JP" and returns a list of plans showing data allowances (e.g. 1 GB, 3 GB, 5 GB, 10 GB, 20 GB), prices in USD, and validity periods (e.g. 7 days, 15 days, 30 days). Ultra plans are marked as monthly subscriptions.

Example 2

"What's the cheapest plan for Germany?"

Expected: The agent calls browse_plans with country: "DE", sorts results by price, and recommends the lowest-priced plan with its data allowance, duration, and exact price.

Example 3

"Buy a 5 GB plan for the US"

Expected: The agent calls browse_plans with country: "US", identifies a ~5 GB plan, then calls create_checkout with the plan ID and country. It returns a checkout session with a payment_url for the user to complete payment, or proceeds with an SPT if one is available.

Known Limitations

Plans are filtered by a single country at a time — multi-country searches require separate calls.
Maximum purchase quantity is 10 plans per checkout session.
Checkout sessions expire after 4 hours.
Ultra plans (is_ultra=true) are monthly billing subscriptions, not one-time purchases.
Agentic payment requires a Shared Payment Token (SPT) from a supported provider.
Not all countries have agentic payment providers — some may only support redirect checkout.
The email parameter is required for the direct purchase flow to associate the order with a customer account.

Common Errors & Troubleshooting

Error	Cause	Resolution
Payment provider not found	The country may not have an agentic payment provider.	Use the redirect checkout flow (`payment_url`) instead.
Plan not found	The `plan_id` does not match any available plan.	Call `browse_plans` to get valid plan IDs for the target country.
Plan does not cover country	The `country` passed to `create_checkout` is not one of the plan's destinations.	Pass the same country code you used in `browse_plans`.
No eSIM plans are available for this country	The country code is valid but Saily sells no plans for it.	Check the destination country code. The destination may not be covered yet.
Payment session expired	Checkout sessions expire after 4 hours.	Call `create_checkout` again to create a new session.
Invalid payment token	The SPT is not scoped to Saily or the mode (test/live) does not match.	Ensure the SPT is created using `network_business_profile` from the checkout response and that test/live modes match.
Country required	The `country` query parameter is missing.	Provide a valid ISO 3166-1 alpha-2 country code.

Privacy & Data Handling

The Saily MCP server processes the minimum data necessary to complete eSIM purchases: country codes for plan lookup, email addresses for order association, and payment tokens for transaction processing. No conversation data or agent interactions are stored beyond what is needed for order fulfillment.

For the full privacy policy, visit saily.com/legal/privacy-policy.

Support

For questions, issues, or integration help, contact the Saily team:

Email: [email protected]
Website: saily.com