Guides: MCP server

The Swell MCP server connects AI assistants such as Claude, ChatGPT, Cursor and Codex to your Swell store. A connected assistant can answer questions about sales, orders, products and customers, and make routine changes: update prices, adjust stock, record shipments and draft discounts. It sees and changes only what you allow, and never more than your own role in the store.

You don't create or paste an API key. You sign in with your Swell account and choose what the assistant can access. Any user of a store can connect, within their role.

You can ask an assistant things like:

"How did sales this month compare with last month?"
"Which products are low on stock?"
"Mark order 1042 as shipped with UPS tracking 1Z999AA10123456784, and notify the customer."
"Draft a 15% off promotion for the summer collection."

💡

What the assistant reads, including customer names, emails and addresses, goes to the AI provider you use, for example Anthropic or OpenAI, and is handled under that provider's terms.

Connect

The server URL is:

https://mcp.swell.store/mcp

You pick the store when you sign in. To tie a connection to one store, for example one connection per client store, use https://mcp.swell.store/mcp/<store-id> instead. <store-id> is the first part of your dashboard address: for https://acme.swell.store/admin it's acme.

Signing in opens a Swell page in your browser. Log in with your Swell account, pick the store if asked, choose the access and click Allow.

Claude

In Claude on the web or desktop, open Customize > Connectors and click + Add > Add custom connector. Enter Swell as the name, enter the server URL and click Add. Then click Connect.

On Team and Enterprise plans, an Owner adds the connector in Organization settings > Connectors, and each member clicks Connect to sign in with their own Swell account.

ChatGPT

Open chatgpt.com/plugins, click + and choose Add custom MCP server. Enter Swell as the name, the server URL as the public endpoint, and OAuth for authentication. Accept the warning and choose Create as a plugin. ChatGPT then sends you to Swell to sign in. Your workspace admin may need to allow custom MCP servers.

Claude Code

Add the server, then run /mcp, select swell and sign in.

claude mcp add --transport http --scope user swell https://mcp.swell.store/mcp

Codex

codex mcp add swell --url https://mcp.swell.store/mcp
codex mcp login swell

Cursor

Add the server to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

{
  "mcpServers": {
    "swell": { "url": "https://mcp.swell.store/mcp" }
  }
}

VS Code

Add the server to .vscode/mcp.json:

{
  "servers": {
    "swell": { "type": "http", "url": "https://mcp.swell.store/mcp" }
  }
}

Access

The sign-in page lists the store's data by area. For each area you choose a level:

None: the assistant can't see the area.
View: the assistant can read records.
Edit: the assistant can also create and change records.

Edit applies only to Products, Discounts, Orders and Customers, the areas with tools that make changes. See Tools. In other areas, View is enough.

Area	Covers
Products	Products with variants, stock and reviews, categories, attributes, purchase links
Gift cards	Gift cards and their balances, without their codes
Discounts	Coupons and promotions
Orders	Orders, carts, shipments and returns
Payments	Payments and refunds
Subscriptions	Subscriptions and their invoices
Customers	Customer accounts with addresses, store credit and saved cards, never card numbers or payment tokens
Content	Your store's content collections
Other	Collections that fit no other area, such as custom collections you created. The page names them. Collections added by installed apps aren't available.

Your role

The access you can allow is limited by your role. If your role only lets you view orders, the page offers View at most. The assistant acts as you, and its changes work like yours in the dashboard. A change to your role reaches the connection within a few minutes.

First connection

In Live, Products, Discounts and Orders start at View and everything else at None. Test starts as not connected. Change any level before you click Allow. Some AI apps ask for specific access up front. The page then selects exactly that, so review it.

More access later

A request that needs access the connection doesn't have doesn't run. Claude shows a prompt to connect, and ChatGPT asks you to reconnect Swell. Either one opens a page that names only what's needed, such as Allow editing Orders, and leaves the rest of the access as it is. If the page can't tell whether the request was for Live or Test, it asks you to choose. If your role doesn't allow the access, the page says so. In AI apps without a prompt, see Troubleshooting.

A few requests need a second area. Searching orders by customer email needs View on Customers, and shipping items by SKU needs View on Products.

Your email address

Some AI apps, such as ChatGPT, also ask for your email address. The page says so when they do. It gives no access to the store.

What the assistant can't do

These limits apply whatever access you allow:

No tool deletes records, refunds, captures or charges a payment, or changes store credit or gift card balances.
cancel_order can't be undone and refunds nothing. It returns a link to settle the payment in the dashboard, and it refuses orders where anything was already shipped or issued.
New products, categories, coupons and promotions are created inactive. The assistant can deactivate them but can't activate them; you do that in the dashboard. Changes to existing records, such as a product's price or sale, its stock, or an active discount, take effect immediately.
cancel_order and create_shipment send the store's notification only when you ask the assistant to notify the customer. Other tools send none. The default cancellation email says a paid order will be refunded, so refund it in the dashboard first.
Installed apps and webhooks react to changes as they do when you edit in the dashboard, so their messages may go out.
Passwords, sign-in and reset tokens, payment tokens, API keys and gift card codes are withheld from results.
For changes the tools don't make, such as an order's items or anything that recalculates tax or shipping, the assistant gives you a link to the right dashboard page.

Most AI apps can ask for your approval before each tool call. We recommend requiring it for every change in Live.

Live and Test

Live is your real store. Test is a separate environment with its own data, for trying changes without affecting customers.

One connection covers both, each with its own access: for example, Edit on Products in Test but only View in Live. The sign-in page shows a box for each. Test starts as Not connected. Turn it on there, or allow it when the assistant first needs it.

When the connection covers both, each action targets one of them, and nothing runs until the assistant names it. Swell also instructs the assistant to:

Ask you which environment, if you didn't say.
Say which environment each answer comes from.
After working in Test, stop before its first change in Live, say what it will change, and wait for you to confirm, even when your request already says Live.

These are instructions to the assistant, not rules Swell can enforce, so turn on approval for changes in Live. To switch, tell the assistant, for example "now do the same in live". There's nothing to reconnect. When the connection covers one environment, every action goes there.

Test is offered when the store has it turned on in Settings > General > Test environment and the store's plan includes it. Otherwise the page offers Live only. A store that hasn't launched yet, such as a partner development store, has only Test.

Revoke access

Each connected assistant appears under Developer > API keys, among the secret keys, named after the AI app, the person and the environment, for example "Claude (Jane Smith) · Live". Revoke it to end that environment's access at once. If the assistant also has Test access, switch the dashboard to Test and revoke "· Test" there too. Store admins who can open API keys see everyone's connections and can revoke any of them.

Revoking only the Live key leaves Test working. The assistant can get Live back only if you approve it again.

Removing Swell in the AI app signs that app out. Some AI apps don't tell Swell, so the key stays listed in Developer > API keys. Revoke it there to be certain. In Claude Code, run claude mcp logout swell before claude mcp remove swell.

Removing a user from the store stops that user's connections within a few minutes. Deactivating the store stops all of them.

Sign-ins renew automatically while you use them. A connection unused for 30 days asks you to sign in again.

Tools

Reading needs View in the area the data belongs to.

Tool	What it does
get_store_context	Store name, dashboard URL, currencies, languages, timezone, and the connection's environments and access
search_products, search_orders, search_customers	Everyday searches by name, SKU, order number, status, dates, totals or stock
get_sales_summary	Sales totals, trends and period comparisons, calculated like the dashboard's sales graph
get_record	One record by ID, SKU, order number or customer email
query_records, list_collections, describe_collection, search_fields, read_guide	Custom queries on any collection the connection can read, with the Backend API reference

Changes need Edit.

Area	Tools
Products	create_product; update_products (text, tags, images, translations, stock tracking; up to 20 products per call); update_product_prices (prices and sales); adjust_stock; create_category; update_category
Discounts	create_coupon, update_coupon, create_promotion, update_promotion
Orders	update_order (notes, hold, shipping name, phone, street and city; shipping edits are usually saved to the customer's address book too); cancel_order; create_shipment
Customers	update_customer (name, phone, group, notes, addresses)

Several stores and devices

The general URL and a store URL make separate connections, each with its own access. To work with several stores, add Swell once per store under its own name, for example per project in Claude Code:

claude mcp add --transport http --scope project swell-acme https://mcp.swell.store/mcp/acme

Partners sign in with their own Swell account and can connect the client stores they manage, within the role each store gives them.

Connecting the same assistant again, from another Claude or ChatGPT account, reuses your existing connection. The page says the assistant is already connected and shows its access, and changes there apply to every account. AI apps that register separately on each computer get a separate connection on each one, with its own keys.

Troubleshooting

You see	What to do
"environment is required"	The connection covers Live and Test. Tell the assistant which one.
"This store has no live environment"	The store hasn't launched yet. Work in Test.
A request fails for lack of permissions in Claude Code, Codex or another AI app without a prompt	Sign in again and allow the added access. In Claude Code, run /mcp and choose Re-authenticate. In Codex, run codex mcp login swell. Elsewhere, use the AI app's MCP settings.
Your store isn't listed when you sign in	You're signed in with another Swell account, or your user hasn't been invited to that store.
"Your role in this store doesn't let you see any of its records"	Ask a store admin to change your role in Settings > Users.
A request for access you didn't expect	Check what the page asks for. If you don't allow it, nothing changes.

For developers

Transport: MCP Streamable HTTP, stateless, POST only.
Authorization: OAuth 2.1 with PKCE (S256). Clients register through client ID metadata documents or dynamic client registration, so no client ID needs to be configured. Metadata is at https://mcp.swell.store/.well-known/oauth-protected-resource/mcp and https://login.swell.store/.well-known/oauth-authorization-server.
Scopes are read_<collection> and write_<collection>, and write includes read. A client that asks only for connect lets the user choose on the sign-in page.
A call without the access it needs returns 403 insufficient_scope with the scopes to request. ChatGPT gets the same challenge in the tool result's _meta["mcp/www_authenticate"].
Every tool except get_store_context takes environment (live or test). It's required while the connection covers both.

To query data directly from code, use the Backend API with a secret key.

Support

For help, see the Help Center. For how Swell handles data from assistants, see the Privacy Policy.