Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Changed the MCP docs to read for merchants, and renamed the docs server page

Damian Legawiecfc0ddaad2bc7
diff --git a/docs/developer/agentic/agent-skills.mdx b/docs/developer/agentic/agent-skills.mdx
index a624805c6c..75c4788af5 100644
--- a/docs/developer/agentic/agent-skills.mdx
+++ b/docs/developer/agentic/agent-skills.mdx
@@ -21,7 +21,7 @@ Projects created with [create-spree-app](/developer/create-spree-app/quickstart)
npx spree add ai
```
-This also connects your agent to the [docs MCP server](/developer/agentic/mcp); pass `--no-mcp` to install only the skills. In any other project, use the skills CLI directly:
+This also connects your agent to the [docs MCP server](/developer/agentic/docs-mcp); pass `--no-mcp` to install only the skills. In any other project, use the skills CLI directly:
```bash
npx skills add spree/agent-skills
diff --git a/docs/developer/agentic/mcp.mdx b/docs/developer/agentic/docs-mcp.mdx
similarity index 99%
rename from docs/developer/agentic/mcp.mdx
rename to docs/developer/agentic/docs-mcp.mdx
index f67f58303f..3d0d60d06f 100644
--- a/docs/developer/agentic/mcp.mdx
+++ b/docs/developer/agentic/docs-mcp.mdx
@@ -1,6 +1,6 @@
---
title: "Docs MCP Server"
-sidebarTitle: MCP
+sidebarTitle: Docs MCP server
description: "Connect Claude, Cursor, or any MCP-compatible AI agent to the Spree docs MCP server to search and read the latest documentation while building."
---
diff --git a/docs/developer/agentic/llm-docs.mdx b/docs/developer/agentic/llm-docs.mdx
index 9796159cc4..72308d7149 100644
--- a/docs/developer/agentic/llm-docs.mdx
+++ b/docs/developer/agentic/llm-docs.mdx
@@ -4,7 +4,7 @@ sidebarTitle: LLM-Ready Docs
description: "Every page of the Spree docs is consumable by LLMs — llms.txt indexes, per-page Markdown, and a local npm package for offline agent reads."
---
-Beyond the [MCP server](/developer/agentic/mcp), the Spree documentation is published in formats designed for direct LLM consumption. Use these when you want to feed docs into a prompt, point a custom agent at an index, or give agents fast local file access.
+Beyond the [MCP server](/developer/agentic/docs-mcp), the Spree documentation is published in formats designed for direct LLM consumption. Use these when you want to feed docs into a prompt, point a custom agent at an index, or give agents fast local file access.
## llms.txt
@@ -50,7 +50,7 @@ node_modules/@spree/docs/dist/
Projects scaffolded with [create-spree-app](/developer/create-spree-app/quickstart) install it automatically.
<Note>
- The package tracks the docs published at install time and is versioned independently of your Spree gems — run your package manager's update to refresh it, and prefer the [MCP server](/developer/agentic/mcp) when you need the absolute latest.
+ The package tracks the docs published at install time and is versioned independently of your Spree gems — run your package manager's update to refresh it, and prefer the [MCP server](/developer/agentic/docs-mcp) when you need the absolute latest.
</Note>
## Generated agent instructions
diff --git a/docs/developer/agentic/overview.mdx b/docs/developer/agentic/overview.mdx
index 72dad3bbf7..a19d7f64e0 100644
--- a/docs/developer/agentic/overview.mdx
+++ b/docs/developer/agentic/overview.mdx
@@ -19,7 +19,7 @@ Spree ships first-class tooling for AI-assisted development. Whether you use Cla
<Card title="Agent Skills" icon="graduation-cap" href="/developer/agentic/agent-skills">
Skills teaching agents Spree's conventions, customization patterns, and upgrade flows — installable into 60+ agent tools, plus a Claude Code plugin with slash commands and safety hooks.
</Card>
- <Card title="Docs MCP Server" icon="plug" href="/developer/agentic/mcp">
+ <Card title="Docs MCP Server" icon="plug" href="/developer/agentic/docs-mcp">
Connect your agent to the Spree documentation MCP server to search and read the latest docs while building.
</Card>
<Card title="Admin MCP Server" icon="store" href="/developer/mcp/overview">
diff --git a/docs/developer/cli/quickstart.mdx b/docs/developer/cli/quickstart.mdx
index 2cc1b98b9d..41eba28c56 100644
--- a/docs/developer/cli/quickstart.mdx
+++ b/docs/developer/cli/quickstart.mdx
@@ -140,7 +140,7 @@ spree add seller-dashboard # the marketplace Seller Panel in apps/seller-dash
spree add ai # Spree agent skills + the docs MCP server for coding agents
```
-`spree add ai` installs the [Spree agent skills](/developer/agentic/agent-skills) and connects Claude Code, Cursor and VS Code to the [docs MCP server](/developer/agentic/mcp). It keeps the MCP servers your config files already list and is safe to re-run. Pass `--no-skills` or `--no-mcp` to set up only one of the two.
+`spree add ai` installs the [Spree agent skills](/developer/agentic/agent-skills) and connects Claude Code, Cursor and VS Code to the [docs MCP server](/developer/agentic/docs-mcp). It keeps the MCP servers your config files already list and is safe to re-run. Pass `--no-skills` or `--no-mcp` to set up only one of the two.
### `spree logs`
diff --git a/docs/developer/contributing/developing-spree.mdx b/docs/developer/contributing/developing-spree.mdx
index a3a69a8496..b12b594c04 100644
--- a/docs/developer/contributing/developing-spree.mdx
+++ b/docs/developer/contributing/developing-spree.mdx
@@ -430,7 +430,7 @@ Issues that are open for 14 days without actionable information or activity will
Spree comes with an [AGENTS.md](https://github.com/spree/spree/blob/main/AGENTS.md) file that instructs coding agents like Claude Code or Codex to help you with your development.
-We also ship [agent skills](/developer/agentic/agent-skills) (`npx skills add spree/agent-skills`), a [docs MCP server](/developer/agentic/mcp), and [LLM-ready documentation](/developer/agentic/llm-docs) — see the [Agentic Development docs](/developer/agentic/overview) for setup across Claude Code, Cursor, Copilot, and other tools.
+We also ship [agent skills](/developer/agentic/agent-skills) (`npx skills add spree/agent-skills`), a [docs MCP server](/developer/agentic/docs-mcp), and [LLM-ready documentation](/developer/agentic/llm-docs) — see the [Agentic Development docs](/developer/agentic/overview) for setup across Claude Code, Cursor, Copilot, and other tools.
The MCP server URL for quick setup:
diff --git a/docs/developer/create-spree-app/quickstart.mdx b/docs/developer/create-spree-app/quickstart.mdx
index 69747803e6..5e972515d9 100644
--- a/docs/developer/create-spree-app/quickstart.mdx
+++ b/docs/developer/create-spree-app/quickstart.mdx
@@ -14,7 +14,7 @@ The CLI walks you through an interactive setup:
1. Include **Next.js Storefront** (default: yes)
2. Include the **Seller Panel**, for marketplaces (default: yes)
-3. **Set up AI coding agents** (default: yes) — installs the [Spree agent skills](/developer/agentic/agent-skills), which teach agents how to work with Spree, and connects Claude Code, Cursor and VS Code to the [Spree docs MCP server](/developer/agentic/mcp) so they can search the latest docs
+3. **Set up AI coding agents** (default: yes) — installs the [Spree agent skills](/developer/agentic/agent-skills), which teach agents how to work with Spree, and connects Claude Code, Cursor and VS Code to the [Spree docs MCP server](/developer/agentic/docs-mcp) so they can search the latest docs
4. **Start Docker services** immediately (default: yes)
Once complete, your store is running at [http://localhost:3000](http://localhost:3000) — setup pulls the latest Spree image, seeds the database, and configures API keys, then prints a summary with your admin credentials and keys. If you skipped starting services, the first `pnpm dev` completes setup automatically.
diff --git a/docs/developer/getting-started/quickstart.mdx b/docs/developer/getting-started/quickstart.mdx
index 3995e9712f..35449ba93d 100644
--- a/docs/developer/getting-started/quickstart.mdx
+++ b/docs/developer/getting-started/quickstart.mdx
@@ -71,7 +71,7 @@ See the [Spree CLI guide](/developer/cli/quickstart) for all commands and the [A
In a hurry? Jump straight to the [tutorial](/developer/tutorial/introduction) to build a feature end to end, the [Next.js Storefront](/developer/storefront/nextjs/quickstart) to put a storefront in front of it, or the [API reference](/api-reference/admin-api/introduction) to see what you can do with the Admin API.
<Tip>
- Using an AI coding agent? `create-spree-app` installs the [Spree agent skills](/developer/agentic/agent-skills) and connects your agent to the [docs MCP server](/developer/agentic/mcp) unless you said no — if you skipped them, run `npx spree add ai` in your project. Your agent then knows the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).
+ Using an AI coding agent? `create-spree-app` installs the [Spree agent skills](/developer/agentic/agent-skills) and connects your agent to the [docs MCP server](/developer/agentic/docs-mcp) unless you said no — if you skipped them, run `npx spree add ai` in your project. Your agent then knows the customization patterns before you write a line of code. See [Agentic Development](/developer/agentic/overview).
</Tip>
---
diff --git a/docs/developer/mcp/custom-tools.mdx b/docs/developer/mcp/custom-tools.mdx
index 3e231f6b4c..7f835a4ec1 100644
--- a/docs/developer/mcp/custom-tools.mdx
+++ b/docs/developer/mcp/custom-tools.mdx
@@ -1,5 +1,5 @@
---
-title: "Custom Tools"
+title: "MCP Server Custom Tools"
sidebarTitle: Custom tools
description: "Add your own tools to the MCP server, or expose a workflow your extension already ships."
---
diff --git a/docs/developer/mcp/overview.mdx b/docs/developer/mcp/overview.mdx
index dfe9f40eed..8e968ccdd6 100644
--- a/docs/developer/mcp/overview.mdx
+++ b/docs/developer/mcp/overview.mdx
@@ -1,54 +1,50 @@
---
title: "MCP Server"
sidebarTitle: Overview
-description: "Your store hosts a Model Context Protocol server, so an AI client can operate it in plain language under the same permissions as the API."
+description: "Your store can be run from an AI assistant — in plain language, and only as far as the person who connected it is allowed to go."
---
-Spree can host a [Model Context Protocol](https://modelcontextprotocol.io) server of its own, so an MCP client — Claude Desktop, claude.ai, Claude Code, Cursor, an in-house agent — can work in your store by talking to it: find products, answer "what did we sell in Germany last month", cancel an order, mark a shipment delivered, add a market.
+Your store can host a server that lets an AI assistant work in it by talking to it. Claude, Cursor, an assistant your team builds — any of them can find products, answer "what did we sell in Germany last month", cancel an order, mark a shipment delivered or add a market.
-It runs inside your Spree application. There is no separate service to deploy, and every request goes through the same tenancy, permission and validation rules as the API itself. An agent does exactly what the person who connected it allows, and nothing else.
+It is part of Spree. There is nothing extra to deploy, and an assistant can only do what the person who connected it could do by clicking.
-## The endpoint
+## The address
```text
https://your-store.com/api/v3/admin/mcp
```
-The back office: the catalog, orders, reporting and store setup, for staff and the agents they connect.
+Paste that into your assistant and it will ask you to sign in.
-<Note>
- One endpoint, one audience. The tools an agent is offered here are the back office's, and a merchant's grant is measured against their own staff permissions — so an agent reaches exactly what the person who connected it can reach.
-</Note>
+This is the back office — the catalog, orders, reporting and store setup — for your staff and the assistants they connect.
-## How it fits together
+## What an assistant gets
-An MCP client speaks JSON-RPC to one endpoint. Behind it:
+- **Things it can do.** 58 of them, each one job: search products, cancel an order, run a report. [The reference](/developer/mcp/tools) lists every one.
+- **Files it can read.** Finished exports, so you can ask about a CSV rather than open it.
+- **What you approved, and no more.** You pick the permissions when you connect. An assistant is never even shown the things you did not approve, so it cannot try them.
-- **Tools** are what the agent can do — one per operation, named for the merchant's language rather than the API's. [The reference](/developer/mcp/tools) lists all 58.
-- **Resources** are files the client can fetch. Finished exports, as CSV.
-- **Consent** decides what any of it reaches. A merchant signs in and approves specific permissions; the agent is never offered a tool outside them.
-
-Every tool reaches data by making a real API request inside the process — the same routing, authentication, record-level authorization and serialization an external client gets. A guard added to the API protects agents without anyone copying it into the tool layer.
+Everything an assistant does runs through the same checks as the rest of your store. There is no side door, and nothing an assistant can reach that your own permissions do not already reach.
## Getting started
<CardGroup cols={2}>
<Card title="Quick start" icon="rocket" href="/developer/mcp/quick-start">
- Install the gem, connect a client, run the first conversation.
+ Connect an assistant and have your first conversation.
</Card>
- <Card title="Tool reference" icon="wrench" href="/developer/mcp/tools">
- All 58 tools, what each is for and which permission it needs.
+ <Card title="What an assistant can do" icon="wrench" href="/developer/mcp/tools">
+ All 58 jobs, and the permission each one needs.
</Card>
<Card title="Permissions and consent" icon="shield-check" href="/developer/mcp/permissions">
- What a merchant approves, how a grant is bounded, revoking access.
+ What you approve, what it can never reach, and how to take access away.
</Card>
<Card title="Custom tools" icon="puzzle-piece" href="/developer/mcp/custom-tools">
- Register your own, and expose a workflow an extension adds.
+ For developers: teach an assistant something your store does.
</Card>
</CardGroup>
## What it is not
-**Not the documentation server.** The [docs MCP server](/developer/agentic/mcp) lets an agent read Spree's documentation while writing code against it. This one operates a live store. They are unrelated and you can use both.
+**Not the documentation server.** The [docs MCP server](/developer/agentic/docs-mcp) lets an assistant read Spree's documentation while someone writes code. This one runs a real store. They are unrelated, and you can use both.
-**Not a replacement for the API.** An agent is good at a merchant's request in words. A scheduled job, a data pipeline or a storefront should call the [Admin API](/api-reference/admin) or the [`spree api` CLI](/developer/cli/admin-api) directly.
+**Not a replacement for the API.** An assistant is good at a request in words. Anything scheduled or automatic — a nightly sync, a data pipeline, a storefront — should use the [Admin API](/api-reference/admin) or the [`spree api` CLI](/developer/cli/admin-api).
diff --git a/docs/developer/mcp/permissions.mdx b/docs/developer/mcp/permissions.mdx
index 404f3d23df..2b53e85e22 100644
--- a/docs/developer/mcp/permissions.mdx
+++ b/docs/developer/mcp/permissions.mdx
@@ -1,60 +1,59 @@
---
-title: "Permissions and Consent"
+title: "MCP Server Permissions and Consent"
sidebarTitle: Permissions
-description: "What a merchant approves when they connect an agent, how a grant is bounded, and how to take it away."
+description: "What you approve when you connect an assistant, what it can never reach, and how to take access away."
---
-An agent acts for the person who connected it. There is no standing credential with nobody behind it, and no key to rotate — the merchant signs in, approves specific permissions, and those permissions are the ceiling for everything that follows.
+An assistant acts for the person who connected it. There is no key to create or rotate: you sign in, tick the permissions you are willing to hand over, and those are its limits from then on.
-## What a merchant approves
+## What you approve
-Connecting sends the merchant to Spree, where a consent screen lists the permissions the client asked for and lets them tick the ones to hand over. The vocabulary is the same as a staff role's — `read_products`, `write_orders` — so a grant is expressed in terms the merchant already understands from the dashboard.
+Connecting takes you to your store, where a screen lists what the assistant has asked for. You tick what to allow. The names are the ones you already know from staff roles — products, orders, reports — so you are approving in the same terms you assign a colleague.
-Three rules bound it:
+Three things are worth knowing:
-**A grant can only narrow.** It is the intersection of what the client asked for and what the approver holds. A staff member who cannot issue refunds cannot approve an agent that can, and a request naming a permission they lack is cut down rather than honoured.
+**You cannot hand over more than you have.** If you cannot issue refunds, you cannot approve an assistant that can. Anything it asked for beyond your own permissions is simply dropped.
-**It is a standing ceiling, not a one-off.** The grant persists until revoked, which is why it is recorded as the intersection rather than as what was asked for. Recorded too wide, it would widen on its own the day that person is promoted.
+**It lasts until you take it back.** This is why your permissions are recorded as they are the day you approve. If you are promoted later, the assistant does not quietly gain what you gained.
-**It is per person.** Each staff member connects for themselves, and an agent's actions are recorded against whoever approved it. **Settings → AI Agents** lists each agent with the people connected through it, what each of them approved, and a revoke beside each — so taking one person's access away leaves their colleagues working.
+**It is yours, not the store's.** Each person connects for themselves, and an assistant's actions are recorded against whoever approved it. Taking one person's access away leaves their colleagues working.
-## What a grant can never hold
+## What it can never reach
-Some permissions are never offered on the consent screen, whatever the client asks for: API keys, integrations, webhook endpoints, roles and staff accounts.
+Some things are never offered, however much an assistant asks:
-These are the permissions that mint *other* credentials. If a grant could hold them, an agent could create an API key with wider scopes than its own, and the ceiling would mean nothing.
+- **API keys, integrations and webhooks.** These create *other* ways into your store. An assistant that could make one could give itself permissions you never approved.
+- **Roles and staff accounts.** For the same reason — an assistant cannot promote anyone, including itself.
+- **Gift card and discount codes.** The code is the money. Anyone who reads one can spend it, so no assistant is shown them.
+- **Erasing a customer.** It cannot be undone, and it should not sit behind a single confirmation. Do it in the dashboard.
-## How the ceiling is enforced
+## Two layers, not one
-A grant narrows at two points, and both matter:
+Approving a permission decides which jobs an assistant is **offered**. What each job then reaches is checked again, against the records themselves.
-**Which tools are offered.** The model is never shown a tool outside the grant, so it does not try and fail — it has no way to ask.
+So an assistant approved for reports can run one — and will still be refused a report broken down by customer unless you also approved customers. And if your store limits a staff member to their own seller's products, an assistant connected by that person is limited the same way.
-**What each call reaches.** Tool visibility is per permission; the data behind it is checked per resource and per record. A connection granted `read_reports` can run a report, and is still refused a dimension exposing customers unless it also holds `read_customers`.
+## Taking access away
-The second matters because the first is about what the model knows, not about what the store allows. Every tool reaches data by making a real API request with the grant's own credential, so a host application's record-level rules — `can :manage, Spree::Product, seller_id: …` — narrow an agent exactly as they narrow a person.
+**Settings → AI Agents** lists each assistant and the people connected through it, with what each person approved and when.
-## Revoking
+Revoking takes effect on the assistant's next request. The registration stays, so the same person can connect again later without an administrator setting it up afresh.
-**Settings → AI Agents** lists everything connected, who approved it and when. Revoking takes effect on that person's next call: it revokes their access rather than the registration, so they stop working immediately, their colleagues carry on, and they can connect again later without the client being registered afresh.
+## Registering an assistant
-## Registering a client
+Before anyone can connect one, the assistant has to be registered for the store — once, under **Settings → OAuth clients**. A registration grants nothing by itself; every permission is decided when a person connects.
-A client is registered once per store, under **Settings → OAuth clients**, before any merchant connects it. A registration carries no permissions of its own — what a client may do is decided per merchant at consent.
+## For things that cannot sign in
-Clients are public rather than confidential: a hosted connector cannot keep a secret, so PKCE is required instead of a client secret.
-
-## For integrations that cannot sign in
-
-A CI job, a nightly sync or a server-side integration has no person behind it and no browser to sign in with. Those use a [secret API key](/developer/cli/admin-api) with its own scopes, which is what API keys are for. The MCP endpoint deliberately refuses them.
+A nightly sync or a server-side integration has no person behind it and no browser to sign in with. Those use an [API key](/developer/cli/admin-api) instead, which is what keys are for. An assistant connection deliberately will not accept one.
## See also
<CardGroup cols={2}>
- <Card title="Tool reference" icon="wrench" href="/developer/mcp/tools">
- Which permission each tool needs.
+ <Card title="What an assistant can do" icon="wrench" href="/developer/mcp/tools">
+ Every job, and the permission it needs.
</Card>
<Card title="Roles and permissions" icon="users" href="/developer/customization/permissions">
- The permission catalog a grant draws from.
+ The permissions you assign to people, which an assistant draws from.
</Card>
</CardGroup>
diff --git a/docs/developer/mcp/quick-start.mdx b/docs/developer/mcp/quick-start.mdx
index 563b71c7f4..181a4cb3ba 100644
--- a/docs/developer/mcp/quick-start.mdx
+++ b/docs/developer/mcp/quick-start.mdx
@@ -1,5 +1,5 @@
---
-title: "Quick Start"
+title: "MCP Server Quick Start"
sidebarTitle: Quick start
description: "Install the MCP server, connect an AI client and run the first conversation against your store."
---
@@ -14,8 +14,7 @@ https://your-store.com/api/v3/admin/mcp
```
<Note>
- Nothing to configure, and no migration for the server itself. The OAuth
- tables ship with `spree_core` and arrive with Spree's other migrations.
+ There is nothing to configure and nothing to set up first.
</Note>
Upgrading an older store, or deliberately removed it? Add the gem back:
@@ -39,7 +38,7 @@ Upgrading an older store, or deliberately removed it? Add the gem back:
## Connect a client
-Paste the URL into your MCP client. It sends you to Spree, you sign in, and you approve what the agent may do.
+Paste the URL into your MCP client. It sends you to your store, you sign in, and you approve what it may do.
<Tabs>
<Tab title="Claude Code">
@@ -80,10 +79,10 @@ Paste the URL into your MCP client. It sends you to Spree, you sign in, and you
</Tab>
</Tabs>
-That is the whole setup. There is no key to mint, paste or rotate — the client discovers how to authorize itself from the endpoint, and you approve it in a browser.
+That is the whole setup. There is no key to create, paste or rotate: your assistant works out where to send you, and you approve it in a browser.
<Note>
- A Spree API key is **not** accepted here, deliberately: an agent acts for a person, so it carries that person's own permissions rather than a standing credential with nobody behind it. For access that cannot sign in — a CI job, a server-side integration — use the [`spree api` CLI](/developer/cli/admin-api).
+ A Spree API key will **not** work here, deliberately: an assistant acts for a person and carries that person's own permissions. For something that cannot sign in — a nightly job, a server-side integration — use the [`spree api` CLI](/developer/cli/admin-api).
</Note>
## Approve what it may do
@@ -92,15 +91,15 @@ Signing in brings up a consent screen listing the permissions the client asked f
What you approve matters more than it looks:
-- **An agent never gets more than you have.** The grant narrows your own permissions, so a staff member who cannot issue refunds cannot approve an agent that can.
+- **It never gets more than you have.** If you cannot issue refunds, you cannot approve an assistant that can.
- **Only what you approved.** Approving product access does not quietly include orders — the tools for anything else are not even offered to the model.
-- **It is yours, not the store's.** Each person connects for themselves, so an agent's actions are recorded against whoever approved it, and revoking one person's access leaves their colleagues working.
+- **It is yours, not the store's.** Each person connects for themselves, so an assistant's actions are recorded against whoever approved it, and revoking one person's access leaves their colleagues working.
[Permissions and consent](/developer/mcp/permissions) covers this in full.
## The first conversation
-The agent picks tools from what you ask; there is no command to learn.
+It works out what to do from what you ask; there is no command to learn.
> **You:** Which products are out of stock, and what did we sell in Germany last month?
@@ -116,17 +115,17 @@ It finds the order, then calls `orders_cancel`. Your client asks you to confirm
## Check what it can see
-Ask the agent directly — `describe_resource` with no arguments lists every resource the connection reaches, and the client's own tool list shows what it was offered. A connection approved for products alone sees roughly a dozen tools rather than all 58.
+Just ask it. It can list everything it reaches, and your assistant's own settings show what it was offered. A connection approved for products alone sees roughly a dozen jobs rather than all 58.
## Troubleshooting
<AccordionGroup>
<Accordion title="The client says the server needs authorization and nothing happens">
- The endpoint advertises its authorization server at `/api/v3/oauth/protected-resource/admin`. If your store sits behind a proxy that rewrites the host, the advertised URL has to be one the browser can reach — check that `Spree::Store#url` and the incoming `Host` header agree.
+ Your assistant asks the store where to send you to sign in. If your store sits behind a proxy or a tunnel that changes the address, the one it is given has to be an address your browser can actually open — so check that your store's configured URL matches the one you reach it on.
</Accordion>
- <Accordion title="Connected, but the agent says it cannot do something">
- It was not granted that permission. **Settings → AI Agents** shows what each connection holds; revoke and reconnect to approve more. Tools outside the grant are not offered at all, so the agent will say it has no way to do it rather than failing mid-call.
+ <Accordion title="Connected, but it says it cannot do something">
+ You did not approve that permission. **Settings → AI Agents** shows what each connection holds; revoke and reconnect to approve more. Anything you did not approve is not offered at all, so it will say it has no way to do it rather than failing halfway.
</Accordion>
<Accordion title="A tool exists but refuses with a permission error">
@@ -134,7 +133,7 @@ Ask the agent directly — `describe_resource` with no arguments lists every res
</Accordion>
<Accordion title="Nothing is listed under AI Agents">
- The page lists each agent registered for the store with the people connected through it. An agent nobody has connected yet shows no one — register it under **Settings → OAuth clients**, then connect from your own client.
+ The page lists each assistant registered for the store with the people connected through it. One nobody has connected yet shows no one — register it under **Settings → OAuth clients**, then connect from your own.
</Accordion>
</AccordionGroup>
@@ -145,12 +144,12 @@ Ask the agent directly — `describe_resource` with no arguments lists every res
All 58 tools and the permission each needs.
</Card>
<Card title="Permissions and consent" icon="shield-check" href="/developer/mcp/permissions">
- How a grant is bounded, and what is out of reach whatever you approve.
+ What you approve, and what is out of reach whatever you do.
</Card>
<Card title="Custom tools" icon="puzzle-piece" href="/developer/mcp/custom-tools">
- Add your own, or expose a workflow your extension ships.
+ For developers: teach an assistant something your store does.
</Card>
<Card title="Admin API" icon="code" href="/api-reference/admin">
- What every tool is dispatching to underneath.
+ The same operations, for code rather than conversation.
</Card>
</CardGroup>
diff --git a/docs/developer/mcp/tools.mdx b/docs/developer/mcp/tools.mdx
index 7513237828..b4406509f8 100644
--- a/docs/developer/mcp/tools.mdx
+++ b/docs/developer/mcp/tools.mdx
@@ -1,15 +1,15 @@
---
-title: "Tool Reference"
+title: "MCP Server Tool Reference"
sidebarTitle: Tools
description: "Every tool the MCP server offers, what it is for and which permission it needs."
---
-58 tools ship with the server. An agent is only ever shown the ones its grant permits, so a connection approved for products alone sees roughly a dozen.
+58 tools ship with the server. An assistant is only ever shown the ones you approved, so a connection for products alone sees roughly a dozen.
The catalog is deliberately not a mirror of the API's 500-odd operations — a tool list that size makes a model worse at choosing, not better. Tools cover the operations a merchant asks for by name; everything else is reached through the three generic ones under [store setup](#store-setup).
<Note>
- The **Permission** column is what a grant must hold for the tool to be offered. A dash means the tool carries no permission of its own and is gated per resource instead: `search_resources` is offered to everyone, but only lists resources the grant can read.
+ The **Permission** column is what you have to approve for the tool to be offered. A dash means it has no permission of its own and is checked per record instead: `search_resources` is offered to everyone, but only finds what you approved.
The last column says whether the tool reads or writes. A write asks your client to confirm before it runs.
</Note>
@@ -110,10 +110,10 @@ The catalog is deliberately not a mirror of the API's 500-odd operations — a t
### Creating, changing and deleting records
-Three tools cover every resource the Admin API can write — 38 of them, from
+Three tools cover everything your store can write — 38 kinds of record, from
products and orders to markets, tax rates and delivery methods — rather than
-one tool per resource. They dispatch to the real endpoint, so a resource whose
-controller runs a workflow gets that workflow.
+one tool each. Creating an order through an assistant does exactly what
+creating one in the dashboard does.
| Tool | Permission | |
| --- | --- | --- |
@@ -123,7 +123,7 @@ controller runs a workflow gets that workflow.
| `tax_exemption_certificates_verify` | `write_customers` | write |
The dash is the point: each call is gated on the resource being written, so a
-grant holding `write_products` can create a product and is refused a market.
+connection approved for products can create a product and is refused a market.
Call `describe_resource` for what a resource accepts.
@@ -135,14 +135,14 @@ Beyond tools, the server offers MCP **resources** — files a client can fetch r
| --- | --- |
| `spree+export://<id>` | A finished export, as CSV. Reading one costs the same permission as reading the records in it, and an export of gift cards or coupon codes is never readable here. |
-A product's media, an order's purchase order and an import's own file are things an agent *puts* there rather than reads back, so they are uploads rather than resources.
+A product's media, an order's purchase order and an import's own file are things an assistant *puts* there rather than reads back, so they are uploads rather than files it can fetch.
## What no tool will do
-Some things are out of reach whatever a grant holds.
+Some things are out of reach whatever you approve.
-- **Credentials.** API keys, integrations, webhook endpoints and gift card codes are never returned by any tool. A gift card code is the money itself, and an integration's settings are where provider credentials live.
-- **Minting another credential.** A grant cannot create API keys, roles, staff accounts or another OAuth client — so an agent can never widen its own reach.
+- **Keys and codes.** API keys, integrations, webhooks and gift card codes are never shown. A gift card code is the money itself, and an integration's settings hold the passwords for another service.
+- **Making another way in.** An assistant cannot create API keys, roles, staff accounts or register another assistant — so it can never widen its own reach.
- **Erasing a customer.** GDPR erasure is irreversible and is not something to put behind a single confirmation prompt. Do it in the dashboard.
- **Codes that spend money.** A gift card or coupon export carries live codes, so no tool creates or reads one. Download it from the dashboard.
@@ -160,7 +160,7 @@ Two things worth knowing about the generic writes:
<CardGroup cols={2}>
<Card title="Permissions and consent" icon="shield-check" href="/developer/mcp/permissions">
- What a merchant approves and how a grant is bounded.
+ What you approve, and what an assistant can never reach.
</Card>
<Card title="Custom tools" icon="puzzle-piece" href="/developer/mcp/custom-tools">
Add your own, or expose a workflow your extension ships.
diff --git a/docs/developer/sdk/quickstart.mdx b/docs/developer/sdk/quickstart.mdx
index f8bf6076ee..098877d3af 100644
--- a/docs/developer/sdk/quickstart.mdx
+++ b/docs/developer/sdk/quickstart.mdx
@@ -86,4 +86,4 @@ await client.wishlists.items.create(wishlistId, params, options);
## Pair with AI agents
-Building your storefront with an AI coding agent? The [Spree agent skills](/developer/agentic/agent-skills) include dedicated SDK and storefront skills (typed clients, Ransack filtering, error handling, custom endpoints), and the [docs MCP server](/developer/agentic/mcp) gives your agent the full SDK reference on demand. See [Agentic Development](/developer/agentic/overview).
+Building your storefront with an AI coding agent? The [Spree agent skills](/developer/agentic/agent-skills) include dedicated SDK and storefront skills (typed clients, Ransack filtering, error handling, custom endpoints), and the [docs MCP server](/developer/agentic/docs-mcp) gives your agent the full SDK reference on demand. See [Agentic Development](/developer/agentic/overview).
diff --git a/docs/developer/tutorial/introduction.mdx b/docs/developer/tutorial/introduction.mdx
index 7baaa0e310..08988377f0 100644
--- a/docs/developer/tutorial/introduction.mdx
+++ b/docs/developer/tutorial/introduction.mdx
@@ -63,5 +63,5 @@ my-store/
</Note>
<Tip>
- Using an AI coding agent? Run `npx spree add ai` in your project before starting — it installs the [Spree agent skills](/developer/agentic/agent-skills) and connects the [docs MCP server](/developer/agentic/mcp). Your agent will know the conventions this tutorial teaches and can follow along with you. See [AI-assisted development](/developer/agentic/overview).
+ Using an AI coding agent? Run `npx spree add ai` in your project before starting — it installs the [Spree agent skills](/developer/agentic/agent-skills) and connects the [docs MCP server](/developer/agentic/docs-mcp). Your agent will know the conventions this tutorial teaches and can follow along with you. See [AI-assisted development](/developer/agentic/overview).
</Tip>
diff --git a/docs/docs.json b/docs/docs.json
index 07501e9360..9d09b3dfa9 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -703,6 +703,10 @@
{
"source": "/developer/agentic/admin-mcp",
"destination": "/developer/mcp/overview"
+ },
+ {
+ "source": "/developer/agentic/mcp",
+ "destination": "/developer/agentic/docs-mcp"
}
],
"contextual": {
@@ -810,7 +814,7 @@
"pages": [
"developer/agentic/overview",
"developer/agentic/agent-skills",
- "developer/agentic/mcp",
+ "developer/agentic/docs-mcp",
"developer/agentic/llm-docs",
"developer/cli/admin-api"
],
@@ -1865,7 +1869,7 @@
"pages": [
"v5/developer/agentic/overview",
"v5/developer/agentic/agent-skills",
- "v5/developer/agentic/mcp",
+ "v5/developer/agentic/docs-mcp",
"v5/developer/agentic/llm-docs"
]
}
@@ -2662,7 +2666,7 @@
"pages": [
"developer/agentic/overview",
"developer/agentic/agent-skills",
- "developer/agentic/mcp",
+ "developer/agentic/docs-mcp",
"developer/agentic/llm-docs"
]
}
diff --git a/docs/plans/6.0-mcp-server.md b/docs/plans/6.0-mcp-server.md
index 59691aa9d5..4e21dad349 100644
--- a/docs/plans/6.0-mcp-server.md
+++ b/docs/plans/6.0-mcp-server.md
@@ -931,6 +931,6 @@ Nothing blocks implementation. One item is deliberately deferred:
- `docs/plans/6.0-dashboard-assistant.md` — the registry's origin; superseded on "No MCP in 6.0"
- `docs/plans/6.0-analytics-semantic-layer.md` step 10 — the reporting tool shape
- `docs/plans/6.0-admin-rbac.md`, `docs/plans/5.5-admin-api-key-scopes.md` — permission catalog and scopes
-- `docs/developer/agentic/mcp.mdx` — the documentation MCP server, a sibling page
+- `docs/developer/agentic/docs-mcp.mdx` — the documentation MCP server, a sibling page
- Official Ruby SDK: https://github.com/modelcontextprotocol/ruby-sdk (1.5.1; 2026-07-28 revision since 1.2.0)
- MCP 2026-07-28 specification changelog: https://modelcontextprotocol.io/specification/2026-07-28/changelog