# MCP server

Source: https://developers.swell.is/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."

> **Note:** 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:

```sh
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.

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

### Codex

```sh
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:

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

### VS Code

Add the server to `.vscode/mcp.json`:

```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:

```sh
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.