--- 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, invoices, 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. | | `get_customer_profile` | Get a customer's profile, contact details, billing details, and customer-level service address. | | `update_customer_profile` | Update confirmed customer name, email, billing-address, and customer-level service-address changes. | | `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` | Prepare a support handover by default, or suspend SIM service when direct action is enabled. | | `restore_subscription` | Restore a customer pause. It refuses payment, fraud, operator, and MCP SIM suspensions. | | `cancel_subscription` | Prepare a support handover by default, or cancel the subscription when direct action is enabled. | | `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. | | `list_invoices` | List a customer's invoices with their lifecycle, balances, currency, due date, and provider reference. | | `list_payment_intents` | List payment collections, including overdue prepaid renewals without invoices, with type, status, due time, and amount. | | `get_invoice` | Get an invoice and its related payment intent, payment attempts, refunds, and billed line items. | | `assess_invoice_recovery` | Check provider payment state and return a safe service-recovery decision or a support handover. | | `prepare_support_handover` | Prepare scoped diagnostic context and a machine-readable topic for a support handover. | | `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. `cancel_subscription` and `block_subscription_sim` require a support handover by default. In this mode, both tools are read-only and do not change service. `MCPSERVER_DIRECT_ACTION_TOOLS` can allow direct actions for a deployment. Set it to a comma-separated list of `cancel_subscription` and `block_subscription_sim`. Set it to `*` to allow every known support-gated action. Set it to `none` to require support for all actions. Unknown tool names stop the MCP server at startup. A directly enabled tool publishes its write and destructive annotations. The server marks `order_new_sim_card` and `remove_from_order` as destructive, but they are not support-gated. Direct cancellation and SIM blocking require the exact `customer_id` and `subscription_id`. They also require `confirmed: true` after the person approves the action. Handovers from `prepare_support_handover` label diagnostics as `CLIENT_REPORTED_UNVERIFIED`. Handovers created inside another tool label diagnostics as `SERVER_OBSERVED`. 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/invoice` | A description of an invoice. | | `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.