Orbit Commerce
Plugin guides

MCP for merchants

Pilot. The merchant connection is live in production for stores on a pilot allowlist: discovery is on, the consent screen has shipped in the store dashboard, and a connected assistant can read and — within the tier the merchant ticks — change the store. A store that is not on the list is refused at the consent step. The section Status: pilot says exactly who can connect today and how to join.

Let a merchant point Claude, or any other MCP client, at their own store — and have it read catalogue data and make changes under permissions the merchant granted and can revoke. For the other MCP surfaces, start at MCP at Orbit.

When to use MCP (and when to build a plugin)

A plugin is code you write and a merchant installs. MCP is different: you write no integration at all. The merchant connects an AI client they already use to their store, and the model calls Orbit's tools directly. Your job as a developer is either to build such a client, or to understand what the surface exposes before you recommend it to a merchant.

MCP connectionPlugin
Who writes the integrationNobody — the model calls toolsYou do
What the merchant installsAn MCP client (e.g. Claude Desktop)Your plugin
Who decides each actionThe model, within granted scopesYour code
CredentialOAuth 2.1 access token, per storeInstall-issued access token
RevocationMerchant, in their dashboardUninstall

If you want deterministic, repeatable behaviour, build a plugin or use a store API key. MCP is for open-ended work a person directs in conversation.

Status: pilot

The transport, discovery and consent screen are all live in production, and connections are open to a pilot group of stores rather than to everyone:

  • Discovery is on: /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server answer 200 on api.myorbitcommerce.net, so any MCP client pointed at the endpoint finds the authorization server on its own.
  • Only stores on a per-store pilot allowlist can mint a connection. The check fails closed: a store that is not on the list is refused on the consent screen, and no token is issued. To join the pilot, email support@myorbitcommerce.net with the store's name.
  • A merchant starts from Settings → AI Assistants in their store dashboard: it shows the address to paste into Claude or ChatGPT (https://api.myorbitcommerce.net/mcp), the assistant sends them back to Orbit's consent screen, they tick the permissions and accept the data terms, and the assistant is connected. Every connection is listed on that page and can be revoked there.

The allowlist is the only gate left before general availability; nothing on this page changes when it is lifted.

The endpoint

POST https://api.myorbitcommerce.net/mcp

It speaks Streamable HTTP, protocol revision 2025-06-18. Every request needs a bearer token; without one you get a 401 carrying the pointer to discovery:

www-authenticate: Bearer error="invalid_token",
  resource_metadata="https://api.myorbitcommerce.net/.well-known/oauth-protected-resource/mcp"

Authorisation

Standard OAuth 2.1 with PKCE, discovered rather than configured. A compliant client needs no Orbit-specific code:

  1. Call the endpoint, get 401, read resource_metadata from the WWW-Authenticate header.
  2. Fetch that document to find the authorization server.
  3. Register dynamically (RFC 7591), then run the authorization-code flow with PKCE (S256 only).
  4. The merchant signs in to their store dashboard, picks a store, and approves a permission tier.
  5. Use the resulting access token as Authorization: Bearer … on /mcp.

The token is bound to one store. A merchant with several stores connects each one separately.

Access tokens last one hour. The refresh token lasts 90 days and slides on use, so a client that is used regularly never needs a new consent; one left idle for 90 days does.

Permission tiers

Merchants do not read scope strings. They choose one of three tiers, and the tier decides which of the grantable scopes the token carries.

TierWhat the merchant seesScopes
1Read only — look at your store data. Nothing can be changed.79
2Safe changes — create and edit drafts. Nothing a shopper can see, and you can undo it.7
3Live and permanent changes — change what shoppers see, or delete things. Includes prices, publishing and deletion.117

Tiers are cumulative: tier 2 includes tier 1, tier 3 includes both, so a tier-3 token carries all 203 grantable scopes. The counts are read from the catalogue the API ships and move as the surface grows; the tier a scope sits in does not.

Tier 2 is deliberately small. A scope earns tier 2 only if every path through it is invisible to shoppers and reversible. Anything that touches a live price, publishes, deletes, sends a message, or spends money is tier 3 — including operations that merely could reach one of those, such as importing media from a URL.

These are the same scope strings the REST API uses, so OAuth scopes describes what each one means. MCP grants a subset: some scopes are never grantable to an AI client at all, and the four devstore:* scopes of the affiliate connection are never offered on a merchant consent screen.

Confirmation on destructive actions

Scopes decide what a token may do. They cannot decide whether a particular call is a good idea, and a model asked to "tidy up the catalogue" can hold a valid tier-3 token and still be about to delete the wrong thing.

Tier-3 tools therefore ask twice. The first call returns a confirmation token together with a description of exactly what will happen. Nothing has changed at that point. The tool only acts when called again with that token, which is single-use and expires after five minutes. Clients surface this to the person as a prompt — the merchant, not the model, approves the irreversible step.

Build this into your client: treat a confirmation response as something a human must see, never as a value to echo back automatically.

Discovering the tools

Do not hard-code a tool list. Call tools/list after connecting — the set depends on the tier the merchant granted, and tools are added over time. Each tool's schema documents its arguments and states whether it is confirmation-gated.

Revocation

A merchant can revoke a connection from their dashboard at any time. Tokens stop working immediately. Treat a sudden 401 on a previously working connection as revocation, not as an error to retry — reconnecting requires fresh consent.

Reference