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.

Document the admin MCP server and register its gem

Damian Legawiec95a08fd0f440
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 32a64aab50..b0b9aa8e04 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -7,6 +7,7 @@ updates:
- "/spree/api"
- "/spree/dashboard"
- "/spree/emails"
+ - "/spree/mcp"
- "/spree/opentelemetry"
- "/spree/providers/*"
schedule:
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 7266d46dab..4751a94042 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -56,7 +56,7 @@ jobs:
- name: Install all project dependencies
run: |
- for project in core api emails providers/easypost providers/meilisearch providers/stripe dashboard opentelemetry; do
+ for project in core api emails providers/easypost providers/meilisearch providers/stripe dashboard mcp opentelemetry; do
echo "--- Installing gems for $project ---"
cd spree/$project
bundle config set --local path ${{ github.workspace }}/vendor/bundle
@@ -101,7 +101,7 @@ jobs:
- name: Install all project dependencies
run: |
- for project in core api emails providers/easypost providers/meilisearch providers/stripe dashboard opentelemetry; do
+ for project in core api emails providers/easypost providers/meilisearch providers/stripe dashboard mcp opentelemetry; do
echo "--- Installing gems for $project ---"
cd spree/$project
bundle config set --local path ${{ github.workspace }}/vendor/bundle
@@ -136,6 +136,8 @@ jobs:
- { project: providers, dirs: "providers/easypost providers/meilisearch providers/stripe", shard: 1, total_shards: 1, procs: 2 }
# dashboard: 1 runner × 2 procs (tiny suite — SPA host)
- { project: dashboard, shard: 1, total_shards: 1, procs: 2 }
+ # mcp: 1 runner × 2 procs (tiny suite — optional MCP server gem)
+ - { project: mcp, shard: 1, total_shards: 1, procs: 2 }
# opentelemetry: 1 runner × 2 procs (tiny suite — optional tracing gem)
- { project: opentelemetry, shard: 1, total_shards: 1, procs: 2 }
services:
@@ -296,6 +298,8 @@ jobs:
- { project: providers, dirs: "providers/easypost providers/meilisearch providers/stripe", shard: 1, total_shards: 1, procs: 2 }
# dashboard: 1 runner × 2 procs (tiny suite — SPA host)
- { project: dashboard, shard: 1, total_shards: 1, procs: 2 }
+ # mcp: 1 runner × 2 procs (tiny suite — optional MCP server gem)
+ - { project: mcp, shard: 1, total_shards: 1, procs: 2 }
# opentelemetry: 1 runner × 2 procs (tiny suite — optional tracing gem)
- { project: opentelemetry, shard: 1, total_shards: 1, procs: 2 }
services:
diff --git a/docs/developer/agentic/admin-mcp.mdx b/docs/developer/agentic/admin-mcp.mdx
new file mode 100644
index 0000000000..72b5fe450e
--- /dev/null
+++ b/docs/developer/agentic/admin-mcp.mdx
@@ -0,0 +1,154 @@
+---
+title: "Admin MCP Server"
+sidebarTitle: Admin MCP
+description: "Let Claude, Cursor or your own agent merchandise the catalog, answer reporting questions and manage store setup in plain language, under the same permissions as the Admin API."
+---
+
+Your store can host a [Model Context Protocol](https://modelcontextprotocol.io) server of its own. Where the [docs MCP server](/developer/agentic/mcp) lets an agent read Spree's documentation, this one lets an agent operate *your* store: find products, answer "what did we sell in Germany last month", cancel an order, mark a shipment delivered, add a market.
+
+It runs inside your Spree application — there is no separate service to deploy — and a request goes through the same tenancy, permission and validation rules as the Admin API. An agent can do exactly what the credential you give it allows, and nothing else.
+
+```text
+https://your-store.com/api/v3/admin/mcp
+```
+
+<Note>
+ The server is an optional gem. Add `spree_mcp` to your `Gemfile` and restart; there is nothing else to configure.
+
+ ```ruby server/Gemfile
+ gem 'spree_mcp'
+ ```
+</Note>
+
+## Mint a key first
+
+The credential is an ordinary Spree secret API key, and its scopes decide what the agent is even told exists. A key that can read orders is never shown a refund tool.
+
+1. In the dashboard, go to **Settings → API keys** and create a **secret** key.
+2. Name it after the agent that will hold it — "Claude Code, orders" — so you know what you are revoking later.
+3. Grant only the scopes that agent needs. `read_products` for a merchandising assistant; add `write_orders` only if it should genuinely be able to cancel and refund.
+4. Copy the key. It is shown once.
+
+Revoking the key in the dashboard is the off switch, and it takes effect on the agent's next call.
+
+<Warning>
+ Give an agent the narrowest scopes that let it do its job. A tool that moves money — refunds, payment capture — is offered to any key holding `write_orders`, and the only thing standing between the model and the action is your client's confirmation prompt.
+</Warning>
+
+## Setup
+
+The key travels as a header on every request. Spree accepts it as `X-Spree-API-Key` — the Admin API's own header — or as `Authorization: Bearer`, for clients that only offer a bearer-token field.
+
+<Tabs>
+ <Tab title="Claude Code">
+ ```bash
+ claude mcp add --transport http spree-admin https://your-store.com/api/v3/admin/mcp \
+ --header "X-Spree-API-Key: sk_your_key"
+ ```
+
+ To share the connection with your team without putting the key in git, commit a project `.mcp.json` that reads it from the environment and let each developer export their own:
+
+ ```json .mcp.json
+ {
+ "mcpServers": {
+ "spree-admin": {
+ "type": "http",
+ "url": "https://your-store.com/api/v3/admin/mcp",
+ "headers": { "X-Spree-API-Key": "${SPREE_API_KEY}" }
+ }
+ }
+ }
+ ```
+ </Tab>
+ <Tab title="Cursor">
+ Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+ ```json
+ {
+ "mcpServers": {
+ "spree-admin": {
+ "url": "https://your-store.com/api/v3/admin/mcp",
+ "headers": { "X-Spree-API-Key": "sk_your_key" }
+ }
+ }
+ }
+ ```
+ </Tab>
+ <Tab title="VS Code (Copilot)">
+ Add to `.vscode/mcp.json`. The `inputs` block prompts for the key instead of storing it in the file:
+
+ ```json
+ {
+ "inputs": [
+ { "id": "spree-key", "type": "promptString", "description": "Spree secret API key", "password": true }
+ ],
+ "servers": {
+ "spree-admin": {
+ "type": "http",
+ "url": "https://your-store.com/api/v3/admin/mcp",
+ "headers": { "X-Spree-API-Key": "${input:spree-key}" }
+ }
+ }
+ }
+ ```
+ </Tab>
+ <Tab title="Your own agent">
+ Any HTTP client works. Post one JSON-RPC message per request:
+
+ ```bash
+ curl https://your-store.com/api/v3/admin/mcp \
+ -H "Content-Type: application/json" \
+ -H "X-Spree-API-Key: sk_your_key" \
+ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+ ```
+ </Tab>
+</Tabs>
+
+<Note>
+ Claude Desktop's connector UI and claude.ai's hosted connectors expect OAuth rather than a header, so they cannot reach this endpoint yet. Every client above can.
+</Note>
+
+## What the agent can do
+
+The tools are not a mirror of the API's endpoints — there would be hundreds, and a catalog that size makes a model worse at choosing. They come in four groups instead.
+
+| Group | Tools | What they are for |
+| --- | --- | --- |
+| Finding things | `describe_resource`, `search_resources`, `get_resource` | Discovering which resources exist and what they can be filtered by, then finding and reading records |
+| Answering with numbers | `describe_reporting`, `query_report` | Revenue, orders and units, sliced by time, product, channel or country — the same figures the dashboard charts show |
+| Doing things | One tool per operation: `orders_cancel`, `fulfillments_mark_delivered`, `products_activate`, `refunds_create`, `price_lists_activate` and around fifty more | Each runs the same workflow the dashboard runs, so validations, emails and webhooks behave identically |
+| Store setup | `create_resource`, `update_resource`, `delete_resource` | Markets, channels, delivery and payment methods, tax rates and the rest of the settings screens |
+
+An agent is only ever shown the tools its key permits, so the list stays small and relevant: a key minted for order operations sees around twenty.
+
+### How a conversation goes
+
+The agent picks tools 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?
+
+The agent calls `describe_resource` to learn that products can be filtered by an `out_of_stock` scope, `search_resources` to list them, then `describe_reporting` and `query_report` for the German figures — and answers in one reply.
+
+> **You:** Cancel order R123456789, refund the customer, and tell them why.
+
+The agent finds the order, then calls `orders_cancel`. Your client asks you to confirm before the call runs; Spree then runs the same cancellation the dashboard runs, and the order's timeline records the API key as the canceller, so an audit later shows which agent did it.
+
+## What it will not do
+
+Some things are deliberately out of reach, whatever scopes the key holds.
+
+- **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.
+- **Erasing a customer.** GDPR erasure is irreversible and is not something to put behind a single confirmation prompt. Do it in the dashboard.
+- **Files.** Media uploads, import files and label downloads. The protocol carries text and structured data.
+- **Order editing.** Adding line items, discounts and fees to an existing order still runs through paths that are not yet workflows. Cancelling, refunding and fulfilling all work today.
+
+## Choosing between this and the CLI
+
+If your agent has a shell, the [`spree api` CLI](/developer/cli/admin-api) is usually the better tool: it reaches every endpoint, handles bulk work, and its output can be piped into other commands. This server is for agents that cannot shell out, and for conversational work where a job-shaped tool beats composing raw HTTP calls.
+
+## See also
+
+- [Docs MCP server](/developer/agentic/mcp) — the same protocol, for reading Spree's documentation
+- [Agent skills](/developer/agentic/agent-skills) — teaching an agent how your team works with Spree
+- [API keys and scopes](/user/settings/api-keys) — minting a key and what each scope grants
+- [Permissions](/developer/customization/permissions) — the catalog the scopes come from
diff --git a/docs/developer/agentic/mcp.mdx b/docs/developer/agentic/mcp.mdx
index d9916c613a..d5ea1c6819 100644
--- a/docs/developer/agentic/mcp.mdx
+++ b/docs/developer/agentic/mcp.mdx
@@ -12,6 +12,13 @@ https://spreecommerce.org/docs/mcp
The server exposes two tools: full-text **search** across the documentation, and **reading** doc pages as Markdown.
+<Note>
+ This server is about Spree's documentation, not your store. To let an agent
+ work on your own catalog, orders and settings, see the
+ [Admin MCP server](/developer/agentic/admin-mcp) — the same protocol, hosted
+ by your application and authenticated with one of your API keys.
+</Note>
+
## Setup
In a [create-spree-app](/developer/create-spree-app/quickstart) project, one command connects Claude Code, Cursor and VS Code at once, and installs the [agent skills](/developer/agentic/agent-skills) too:
@@ -79,6 +86,7 @@ To connect a single tool by hand, or one outside a create-spree-app project:
| **MCP server** (this page) | The latest published docs; agents working outside a scaffolded project; questions the installed skills don't cover |
| **[`@spree/docs` npm package](/developer/agentic/llm-docs)** | Fast local reads inside a project — no network round-trip, works offline, pinned to what you installed |
| **[Agent skills](/developer/agentic/agent-skills)** | Conventions and how-to knowledge the agent should apply without searching at all |
+| **[Admin MCP server](/developer/agentic/admin-mcp)** | Not docs at all — operating a real store: its catalog, orders, reports and settings |
<Note>
New [create-spree-app](/developer/create-spree-app/quickstart) projects come connected (skip it with `--no-docs-mcp`) — Claude Code asks you to approve the server the first time you open the project. The project's `AGENTS.md` tells agents to search here and read pages from the local `@spree/docs` package, which matches the Spree version the project runs.
diff --git a/docs/developer/agentic/overview.mdx b/docs/developer/agentic/overview.mdx
index b8d7ccd638..1bacb939bb 100644
--- a/docs/developer/agentic/overview.mdx
+++ b/docs/developer/agentic/overview.mdx
@@ -22,6 +22,9 @@ Spree ships first-class tooling for AI-assisted development. Whether you use Cla
<Card title="Docs MCP Server" icon="plug" href="/developer/agentic/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/agentic/admin-mcp">
+ Let an agent run your store — merchandise the catalog, answer reporting questions, manage orders and setup — under the same permissions as the Admin API.
+ </Card>
<Card title="LLM-Ready Docs" icon="file-text" href="/developer/agentic/llm-docs">
llms.txt, per-page Markdown, and the `@spree/docs` npm package for fast local reads.
</Card>
diff --git a/docs/docs.json b/docs/docs.json
index 8849c145db..cd18145087 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -807,6 +807,7 @@
"developer/agentic/overview",
"developer/agentic/agent-skills",
"developer/agentic/mcp",
+ "developer/agentic/admin-mcp",
"developer/agentic/llm-docs",
"developer/cli/admin-api"
],
@@ -2648,6 +2649,7 @@
"developer/agentic/overview",
"developer/agentic/agent-skills",
"developer/agentic/mcp",
+ "developer/agentic/admin-mcp",
"developer/agentic/llm-docs"
]
}
diff --git a/spree/Rakefile b/spree/Rakefile
index 418fff5d07..040f679595 100644
--- a/spree/Rakefile
+++ b/spree/Rakefile
@@ -8,7 +8,7 @@ rescue LoadError
end
SPREE_CORE_GEMS = %w(core api).freeze
-SPREE_OPTIONAL_GEMS = %w(emails dashboard opentelemetry).freeze
+SPREE_OPTIONAL_GEMS = %w(emails dashboard mcp opentelemetry).freeze
# Provider gems sit one directory deeper and their gem name doesn't match the
# directory, so they carry the path explicitly.
SPREE_PROVIDER_GEMS = {
diff --git a/spree/mcp/README.md b/spree/mcp/README.md
new file mode 100644
index 0000000000..18584f9188
--- /dev/null
+++ b/spree/mcp/README.md
@@ -0,0 +1,24 @@
+# Spree MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for the
+Spree back office. Any MCP client — Claude Code, Cursor, an in-house agent —
+can merchandise the catalog, answer reporting questions and manage store setup
+in plain language, under the same tenancy and permission rules as the Admin
+API.
+
+```ruby
+gem 'spree_mcp'
+```
+
+The endpoint is `POST /api/v3/admin/mcp`, authenticated with a Spree secret API
+key sent as `X-Spree-API-Key: sk_…` or `Authorization: Bearer sk_…`. The key's
+scopes decide which tools the model is offered, so an agent is never told about
+a capability its credential does not carry.
+
+This gem is a protocol adapter and nothing more. The tools, their schemas and
+the permissions gating them live in `spree_core` as `Spree.agent_tools`, which
+means an extension registers a tool without depending on this gem, and the
+dashboard assistant offers the same tools over a different transport.
+
+See the [documentation](https://spreecommerce.org/docs/developer/agentic/admin-mcp)
+and `docs/plans/6.0-mcp-server.md`.