MCP server

Seamless OS ships a remote Model Context Protocol 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.

Endpoint

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

https://mcp.example.com/mcp

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

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

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.

Emergency address approval

Call get_subscription with subscription_ids set to the selected subscription ID. Do not combine it with customer_id. Read items[].subscription.serviceAddress.address. Show this address to the person and ask for approval for emergency services. Do not use the address from get_customer_profile for this approval.

After approval, call enable_wifi_calling with the exact customer and subscription IDs and confirmed=true. Copy the approved address into confirmed_service_address. The address object uses street, street2, city, state, zip, country, region, and attention. The tool requires street, city, zip, and country. Refresh a cached MCP tool schema before you call this tool. Older clients that do not send confirmed_service_address fail. This change does not revise the public API v2 request.

The server compares the approved address with the current effective service address when it receives the command. If the address changes, read the subscription again and ask for approval again. This check does not prove what the person saw. It does not keep the address fixed during a later workflow.

Tool availability and effects

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

The server registers generate_us_port_out_pin only when the deployment country is US.

cancel_subscription, block_subscription_sim, reset_network_services, create_customer_user, and generate_us_port_out_pin require a support handover by default. In this mode, the tools are read-only and do not change customer access or service.

MCPSERVER_DIRECT_ACTION_TOOLS can allow direct actions for a deployment. Set it to a comma-separated list of cancel_subscription, block_subscription_sim, reset_network_services, create_customer_user, and generate_us_port_out_pin. 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.

reset_network_services prepares a read-only support handover by default. A deployment must set FEATURE_END_USER_RESET_NETWORK_SERVICES=true and allow reset_network_services through MCPSERVER_DIRECT_ACTION_TOOLS to enable a direct reset. The API endpoint uses the feature setting and returns 501 Not Implemented when the setting is false or absent. A direct reset requires the exact customer_id and subscription_id. It also requires confirmed: true after the person approves the service interruption. The tool does not change Seamless OS barring or data-bucket configuration. The provider workflow can change network-side balances or shared data groups on some networks. Enable the tool only when the customer accepts these provider-specific risks.

Direct customer-user creation requires an explicit customer_id, the new user’s name and email, and MANAGER access. The confirmation sentence must name the user, email, customer, and role. The caller must hold the customer-management permission and manager authority. The tool does not grant brand-wide administrator access.

Direct port-out PIN generation requires the exact customer_id and subscription_id. It also requires confirmed: true after the person approves that the previous PIN stops working. The tool returns the new PIN and its expiry, so the PIN passes through the model. A subscription that cannot port out, for example during a binding period, gets no PIN.

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:

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