MCP server

Connect AI agents and assistants to Seamless OS through the Model Context Protocol (MCP) server

Seamless OS ships a remote Model Context Protocol server. Through it an AI agent can read customers, subscriptions, licenses, catalogs, orders, SIM cards, and usage data. It can also purchase offerings and change subscription service. ChatGPT, Cursor, VS Code Copilot, and your own agent can connect to it.

The server is deployed per brand, beside your API. Every tool runs with the permissions of the signed-in user, so an agent sees and changes only what the person who authorized it can. The server is in preview. Its tools, its resources, and their schemas can still change.

A separate server, with no authentication, exposes this documentation site to an agent. Read Docs for agents.

Endpoint

Transport	URL	Notes
Streamable HTTP	`https://mcp.example.com/mcp`	Recommended for all current MCP clients.
SSE (legacy)	`https://mcp.example.com/sse`	For clients that have not yet migrated to Streamable HTTP.

Replace mcp.example.com with the MCP domain of your deployment. It sits next to your API domain.

Statelessness

The /mcp endpoint implements the stateless Streamable HTTP transport of the 2026-07-28 MCP revision. Every request is one self-contained HTTP POST, and the server keeps no state between two requests.

The server speaks protocol versions 2025-03-26 to 2026-07-28, which is every revision of Streamable HTTP. A client on an older revision opens with an initialize handshake and still works. The server answers the handshake, but it never issues a session. A client on the 2024-11-05 revision predates Streamable HTTP, so it uses the legacy /sse transport.
The server issues no Mcp-Session-Id header, and it ignores one that an older client sends. No session exists, so no session expires. A long-running agent never loses its connection state between two calls.
GET and DELETE on /mcp answer 405 Method Not Allowed. There is no separate server-push stream. An older protocol revision requires a client to tolerate exactly this from a server with no sessions and no push stream.
When the client closes the response stream, the server cancels the request, and it cancels the API calls that the request started.

Each request carries everything that the server needs. A load balancer can send it to any replica, with no session affinity.

Authentication

The server implements the standard MCP authorization flow: OAuth 2.0 with dynamic client registration and metadata discovery. The two discovery documents are /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource.

As a result, you configure nothing. Put the server URL into an MCP client. The client registers itself and opens a browser window, and you sign in there with your ordinary Seamless OS account. The sign-in is the login page of the brand portal, or a hosted page for your email address and a verification code. Which one you get depends on the deployment. The client then holds a token scoped to your user, and every tool call is authorized as you.

Connect a client

claude mcp add --transport http seamless-os https://mcp.example.com/mcp

Claude Code discovers the OAuth configuration and prompts you to sign in on first use.

In ChatGPT, turn on developer mode at Settings → Connectors → Advanced → Developer mode. Developer mode is available on a paid plan. Then go to Settings → Connectors → Create and enter this URL:

https://mcp.example.com/mcp

ChatGPT opens the sign-in flow when you create the connector. Then enable the connector in a conversation to use its tools.

Add the server to .cursor/mcp.json:

{
  "mcpServers": {
    "seamless-os": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Cursor handles OAuth registration and sign-in automatically.

Add the server to .vscode/mcp.json:

{
  "servers": {
    "seamless-os": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

VS Code handles OAuth registration and sign-in automatically.

Tools

Start a conversation with get_context. It returns the signed-in user and the data that the user can access. The server applies the same access rules to every other tool.

Tool	What it does
`get_context`	Get the user, accessible customers, and one customer’s subscriptions, active licenses, open orders, and brand.
`search`	Find accessible entities by phone number, portal URL, ID, reference ID, name, or email address.
`get_portal_link`	Get an account-scoped portal link for work that no MCP tool supports.
`list_product_offerings`	List a personalized catalog, or list the plan and add-on options for a subscription.
`get_subscription`	List or fetch subscriptions with their add-ons. The list supports filters and cursor pagination.
`add_to_order`	Add a subscription, plan change, add-on, top-up, or external product to a draft order.
`order_new_sim_card`	Create a replacement SIM-card order from a catalog offering. The tool submits a priced zero-total order.
`remove_from_order`	Remove a line item from a draft order.
`get_order`	List a customer’s order summaries, or get one full order with its state, items, price, validation, and created entities.
`checkout_order`	Create a temporary storefront link where the customer can review, complete, and pay for a draft order.
`block_subscription_sim`	Suspend a subscription’s service immediately or on a specified date.
`restore_subscription`	Restore a suspended, paused, or blocked subscription immediately or on a specified date.
`cancel_subscription`	Permanently cancel a subscription on the selected schedule and record the churn reason.
`get_subscription_esim_qr_code`	Get the eSIM activation string, its expiration, and a hosted QR-code URL when one is available.
`get_subscription_usage`	Get data, voice, SMS, and MMS allowance use across a subscription’s base plan and add-ons.
`list_licenses`	List a customer’s licenses by type, with product offerings, prices, and cursor pagination.
`get_app_config`	Get the deployment’s country, currency, internal brand name, and portal URL.
`get_available_enums_by_name`	List the valid enum values for a supported entity name.
`get_domain_help`	Get descriptions of the domain entities and their relationships.

Tool availability and effects

The server does not register get_subscription_usage when the deployment has no usage service.

The server does not register cancel_subscription by default. A deployment can register it with MCPSERVER_IRREVERSIBLE_TOOLS_ENABLED. Without this setting, a person must cancel in the portal.

cancel_subscription is irreversible through MCP. The server marks it as destructive. The server also marks block_subscription_sim, order_new_sim_card, and remove_from_order as destructive. These three tools are not irreversible.

Each tool publishes MCP annotations for read-only, destructive, idempotent, and open-world effects when these annotations apply. A client can use these annotations before it permits a tool call.

Resources

The server publishes these fixed resources:

Resource	What it contains
`json://config/app`	The country, currency, internal brand name, and portal URL.
`json://users/me`	The signed-in user and the customers that the user can access.
`text://entities/app_config`	A description of the application configuration.
`text://entities/customer`	A description of a customer.
`text://entities/license`	A description of a license.
`text://entities/order`	A description of an order.
`text://entities/products/catalog`	A description of a personalized product catalog.
`text://entities/subscription`	A description of a subscription.
`text://entities/user`	A description of a user.

The get_domain_help tool returns the same entity descriptions.

The server also publishes these resource templates:

json://products/catalogs/{customer_id} — A customer’s personalized product catalog.
json://config/enums/{entity_name} — The valid enum values for a supported entity name.

The server does not publish MCP prompts.

Next steps

API reference

The API the MCP tools are built on.

Authentication

How Seamless OS authenticates users and API calls.