--- title: MCP server description: Connect AI agents and assistants to Seamless OS through the Model Context Protocol (MCP) server --- Seamless OS ships a remote [Model Context Protocol](https://modelcontextprotocol.io) 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](/developer-guide/docs-for-agents.md). ## 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](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http). 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 Code** ```bash 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. **ChatGPT** 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. **Cursor** Add the server to `.cursor/mcp.json`: ```json { "mcpServers": { "seamless-os": { "url": "https://mcp.example.com/mcp" } } } ``` Cursor handles OAuth registration and sign-in automatically. **VS Code** Add the server to `.vscode/mcp.json`: ```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](/api-reference.md) — The API the MCP tools are built on. - [Authentication](/api-reference/authentication.md) — How Seamless OS authenticates users and API calls.