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.

Documented connecting an agent by signing in

Damian Legawiec043e140d739e
diff --git a/docs/developer/agentic/admin-mcp.mdx b/docs/developer/agentic/admin-mcp.mdx
index e093c4a8d1..bfd3c3a14b 100644
--- a/docs/developer/agentic/admin-mcp.mdx
+++ b/docs/developer/agentic/admin-mcp.mdx
@@ -20,9 +20,34 @@ https://your-store.com/api/v3/admin/mcp
```
</Note>
+## Two ways to connect
+
+| | Who it is for | What the agent may do |
+| --- | --- | --- |
+| **Sign in** (OAuth) | A merchant connecting a consumer client — claude.ai, Claude Desktop, ChatGPT | What the signed-in person approves, never more than their own role allows |
+| **A secret API key** | A developer configuring an agent they run themselves — Claude Code, Cursor, VS Code, your own code | Exactly the scopes on the key |
+
+Signing in needs nothing created first: paste your store's MCP URL into the client, and it will walk you through approving access. Everything below the next section is the key-based path.
+
+## Signing in
+
+A consumer client asks for your store URL, then opens a Spree page listing what it wants to do. Approve it and the client is connected; nothing is copied or pasted.
+
+```text
+https://your-store.com/api/v3/admin/mcp
+```
+
+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.
+- **Only what you approved.** Approving product access does not quietly include orders — the tools for anything else are not even offered.
+- **Revoke whenever you like.** **Settings → Connected apps** lists everything connected, with the last time each was used. Revoking stops it on its next call.
+
+Each person connects for themselves, so an agent's actions are recorded against the person who approved it.
+
## 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.
+For an agent you run yourself, 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.
@@ -35,7 +60,7 @@ Revoking the key in the dashboard is the off switch, and it takes effect on the
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
+## Setup with a key
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.
@@ -107,7 +132,7 @@ The key travels as a header on every request. Spree accepts it as `X-Spree-API-K
</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.
+ Every client above carries the key in its own configuration. A consumer connector — claude.ai, Claude Desktop's connector UI, ChatGPT — has nowhere to put one: it connects from the vendor's servers rather than your machine. Those sign in instead, as described above.
</Note>
## What the agent can do
@@ -196,7 +221,7 @@ A tool is offered only to a credential holding its `permission`, so a key that c
## 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.
+The [`spree api` CLI](/developer/cli/admin-api) reaches every endpoint, handles bulk work, and its output pipes into other commands, so an agent with a shell should generally use it. Reach for this server when the shell is not available, or when the work is conversational — a tool shaped like "cancel this order" gives a model far less room to go wrong than composing the HTTP call itself, and each one runs the same workflow the dashboard runs.
## See also
diff --git a/docs/plans/6.0-mcp-oauth.md b/docs/plans/6.0-mcp-oauth.md
new file mode 100644
index 0000000000..d1fe7bdfa7
--- /dev/null
+++ b/docs/plans/6.0-mcp-oauth.md
@@ -0,0 +1,178 @@
+# MCP OAuth 2.1 Authorization Server
+
+**Status:** Implemented — shipped with `6.0-mcp-server` in one pull request. Client ID metadata documents are explicitly 6.1 work (see Migration Path step 6).
+**Target:** Spree 6.0
+**Depends on:** `6.0-mcp-server` (the tool catalog and transport this authenticates), `6.0-platform-auth` (the admin user and permission models a grant binds to)
+**Author:** Damian Legawiec
+**Last updated:** 2026-10-05
+**Tracking:** Linear — · GitHub —
+
+## Summary
+
+The Admin MCP server shipped in 6.0 authenticates with a secret API key in a
+header. That reaches agents whose configuration a developer edits — Claude
+Code, Cursor, VS Code, in-house clients — and no further. It does not reach a
+merchant, because every path that carries a header to a consumer client
+requires either a terminal or a vendor's proprietary feature. Hosted
+connectors (claude.ai, ChatGPT) connect from the vendor's own servers and
+offer exactly one interoperable way in: OAuth 2.1.
+
+This plan makes Spree an OAuth 2.1 authorization server for its own MCP
+endpoint, so a merchant connects their store by entering its URL, signing in
+with the admin account they already have, and approving a consent screen. The
+tool catalog, scope filtering, store scoping and credential filtering from
+`6.0-mcp-server` are unchanged — this is a second front door onto the same
+house.
+
+Without it the MCP server reaches only agents whose configuration a developer
+edits, and for those the `spree api` CLI is the better tool — so a key-only
+MCP server is a second surface that loses to one Spree already has. Consumer
+reach is what makes it a feature rather than a duplicate.
+
+## Key Decisions (do not deviate without discussion)
+
+- **Spree is the authorization server, not a client of one.** This is the
+ opposite direction from `6.0-platform-auth` phase 7, which makes Spree an
+ OIDC *client* so staff can sign in through Okta. The two share a spec family
+ and almost no code; neither one provides the other. A merchant on a
+ self-hosted store has no external IdP to delegate to, and requiring one
+ would exclude the installations this feature exists for.
+- **Doorkeeper, not hand-rolled.** It carries the parts that are dangerous to
+ get wrong — PKCE S256, token issuance and rotation, grant replay detection,
+ public-client hardening — and as of 6.0 it also carries RFC 8707 resource
+ indicators and the port-agnostic loopback redirect that Claude Code needs.
+ What it does not carry is the discovery layer, which is small and
+ declarative.
+- **The API key path stays, permanently.** It is not a stopgap that OAuth
+ retires. A header is how a CI job, a server-side integration and a
+ developer's editor authenticate, and none of them should be made to run a
+ browser flow. commercetools ships both deliberately; so do we.
+- **No dynamic client registration.** The 2026-07-28 revision deprecated
+ RFC 7591 in favour of client ID metadata documents, Doorkeeper never
+ supported DCR, and neither claude.ai nor ChatGPT requires it. Pre-registered
+ client IDs are first in the spec's own priority order and carry the first
+ release; CIMD follows when Doorkeeper's support lands.
+- **A grant binds to a real admin user, never to a store.** The token's
+ authority is that user's own permissions at call time, so revoking the user
+ or narrowing their role takes effect on the next request without touching
+ the grant. This is what the API key path cannot do: one key is one blob of
+ scopes with no person behind it.
+- **A 401 is reserved for an authorization challenge.** The endpoint already
+ answers a missing or unrecognised credential with 401, which is what an
+ OAuth-capable client needs in order to begin discovery, and a permission
+ refusal is already not an HTTP error at all — it comes back as
+ `{ error: '…' }` in a 200 JSON-RPC response, which is where MCP puts
+ tool-level failures and what lets a model correct itself. That split is
+ what OAuth depends on, so it has to survive: a 401 on a request that
+ authenticated would send a consumer client into a re-authorization loop.
+
+## Design Details
+
+### What the spec actually requires
+
+Authorization is `OPTIONAL` in the 2026-07-28 revision — the header-only
+server from 6.0 is already compliant. The `MUST`s bind only once authorization
+is implemented, and partial implementation is worse than none, so the three
+that matter are non-negotiable from the first release:
+
+| Requirement | Who provides it |
+| --- | --- |
+| **RFC 9728** Protected Resource Metadata at `/.well-known/oauth-protected-resource` | Hand-written. `resource` must equal the URL the merchant typed, path included |
+| **RFC 8414** Authorization Server Metadata, advertising `code_challenge_methods_supported: ["S256"]` | Hand-written, or OIDC discovery via `doorkeeper-openid_connect` |
+| **PKCE** S256, and **RFC 8707** audience-restricted tokens | Doorkeeper 6.0 |
+
+Omitting `code_challenge_methods_supported` makes compliant clients refuse to
+connect at all, which fails closed in a way that is hard to read from the
+client side — so the metadata documents get their own request specs asserting
+each required field, not just a 200.
+
+### The challenge
+
+The MCP endpoint's existing 401 grows a header naming where to discover the
+rest:
+
+```
+WWW-Authenticate: Bearer resource_metadata="https://store.example.com/.well-known/oauth-protected-resource", scope="read_products write_orders"
+```
+
+`scope` is a `SHOULD` added in this revision and worth including: it lets a
+client ask for the right authority up front rather than discovering the gap
+after consent.
+
+### Consent
+
+The screen a merchant approves is the only part of this a person reads, so it
+names what it is granting in the permission catalog's own words rather than
+raw scope strings — "Read products", "Cancel and refund orders" — and it names
+the client. A grant is listed in the dashboard beside API keys, with the same
+revoke affordance, because a merchant who wants to disconnect an agent should
+not have to learn which of two mechanisms it used.
+
+### Audience validation
+
+Every token is checked to have been issued for this resource. This is the
+defence against a token minted for another service being replayed here, and
+Doorkeeper's resource-indicator support supplies the `aud` to check — but the
+check itself lives in our endpoint and gets its own spec, because a missing
+audience check is invisible until it is exploited.
+
+## Migration Path
+
+1. **Doorkeeper in, migrations, no endpoints yet.** The gem, its tables, and
+ the configuration: PKCE forced, public clients, resource indicators
+ enabled, loopback redirects port-agnostic.
+2. **Discovery documents.** RFC 9728 and RFC 8414, with the `resource`
+ derived from the request so a store on a custom domain answers correctly.
+3. **The challenge and audience validation** on the MCP endpoint. At this
+ point Claude Code can complete a flow, which makes the whole path testable
+ before any consumer client is involved.
+4. **Consent screen and dashboard management.** Grants listed and revocable
+ beside API keys.
+5. **Pre-registered client IDs** for claude.ai and ChatGPT, with their
+ documented callback URLs, and the docs page rewritten around "enter your
+ store URL and sign in".
+6. **CIMD**, when Doorkeeper's support ships. Until then step 5 carries the
+ consumer clients.
+
+Steps 1–3 are the substance; a merchant sees nothing until 4 and 5.
+
+## Constraints on Current Work
+
+- **Do not retire the API key path.** Anything built on the assumption that
+ MCP authentication means OAuth will break the developer clients that work
+ today.
+- **Do not widen the 401.** It means "no usable credential", nothing else.
+ Permission refusals stay as `{ error: '…' }` inside a 200, where MCP puts
+ tool-level failures; promoting one to an HTTP status would send consumer
+ clients into a re-authorization loop.
+- **Do not add a second permission model.** A grant's authority is the admin
+ user's own, resolved at call time through the same ability the dashboard
+ uses. Scopes on a grant narrow that authority; they never extend it.
+- **The tool catalog is untouched.** `Spree.agent_tools`, the resource map and
+ the credential filter are shared by both authentication paths and must not
+ learn which one a request used.
+
+## Open Questions
+
+- **Client ID metadata documents.** Deferred: Doorkeeper's support is an open
+ pull request, and pre-registered client IDs are first in the spec's own
+ priority order, so the consumer clients work without it. Revisit when that
+ lands — it is what would let a client connect without being seeded.
+- **One authorization server per installation, or per store?** Settled as
+ per-store resource identifiers over one installation-wide token store: the
+ identifier must match the URL the merchant typed, and
+ `Spree::Api::Oauth.register_resource` derives it from the store. A
+ multi-store installation therefore serves one metadata document per store
+ per protected resource.
+
+## References
+
+- `docs/plans/6.0-mcp-server.md` — the tool catalog, transport and key-based auth this extends; its Open Questions deferred exactly this work
+- `docs/plans/6.0-platform-auth.md` phase 7 — OIDC *login*, the client side; explicitly not a substitute
+- `docs/plans/5.5-admin-api-key-scopes.md` — the scope catalog a grant narrows
+- MCP 2026-07-28 authorization: https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization
+- Client ID metadata documents: https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/
+- Doorkeeper RFC 8707 resource indicators: https://github.com/doorkeeper-gem/doorkeeper/pull/1886
+- Doorkeeper CIMD (open): https://github.com/doorkeeper-gem/doorkeeper/pull/1956
+- Doorkeeper port-agnostic loopback: https://github.com/doorkeeper-gem/doorkeeper/pull/1960
+- Vendure's MCP plugin, the closest precedent — self-hosted, is its own authorization server: https://github.com/vendurehq/vendure/pull/5262
diff --git a/docs/plans/6.0-mcp-server.md b/docs/plans/6.0-mcp-server.md
index fb8d944945..690da4402d 100644
--- a/docs/plans/6.0-mcp-server.md
+++ b/docs/plans/6.0-mcp-server.md
@@ -717,17 +717,23 @@ and any later adapter inherit them rather than rediscovering them:
## Open Questions
-Nothing blocks implementation. Two items are deliberately deferred:
+Nothing blocks implementation. One item is deliberately deferred:
- **OAuth 2.1 for hosted consumer connectors** (claude.ai connectors,
- ChatGPT). Unblocked by Spree gaining an authorization-server capability, or
- by a decision to delegate to an external one; `6.0-platform-auth` phase 7
- (OIDC login) does not provide it. The 2026-07-28 revision replaced dynamic
- client registration with client ID metadata documents, so that design
- should start from the current spec, not the 2025 one.
-- **A `spree mcp` CLI command** (config printer or stdio proxy). Unblocked by
- a client that cannot reach a Streamable HTTP endpoint, or by setup friction
- reported from the docs page in step 6.
+ ChatGPT) — built alongside this, see `6.0-mcp-oauth`. Key-based
+ authentication reaches agents whose configuration a developer edits, and no
+ further: every other way of carrying a header to a consumer client needs
+ either a terminal or a single vendor's proprietary feature, so OAuth is
+ what makes this a merchant feature rather than a developer one. The tool
+ catalog, scope filtering and credential filter here are unchanged by it —
+ a grant resolves into the same `Spree::AgentTools::Context`, narrowed to
+ what the merchant approved.
+- **A `spree mcp` CLI command** (config printer or stdio proxy). A stdio
+ bridge would let a desktop client reach this endpoint without OAuth, and is
+ the common pattern among self-hosted platforms, but it needs Node and a
+ hand-edited config file — so it serves the developer audience the CLI
+ already serves better, not the merchant. Worth building only as a
+ convenience for those clients, never as the answer to consumer reach.
## References
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 79e769fa1e..147401a1da 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -6189,6 +6189,98 @@ seller reset requests are declared `webhook: false` and never reach any
webhook endpoint, whatever it subscribes to — the rule 5.x kept in the
subscriber's `NON_DELIVERABLE_EVENTS`, now read from the catalog.
+## 2026-10-05 — MCP consumer reach needs OAuth; nothing else is both interoperable and merchant-grade
+
+The Admin MCP server shipped in 6.0 authenticates with a secret key in a
+header, which reaches agents whose configuration a developer edits and no
+further. Reviewing that against what merchants actually need closed every
+alternative to OAuth 2.1, so `6.0-mcp-oauth` plans it and it ships in the
+same pull request.
+
+**A developer-only MCP server is worse than none.** The `spree api` CLI
+already serves agents with a shell, with full endpoint coverage and pipeable
+output. An MCP server reaching only that audience is a second surface to
+maintain that loses to the first, so consumer reach is the feature's
+acceptance criterion rather than an enhancement to it.
+
+**A stdio bridge does not deliver it.** Shipping a local proxy that injects
+the header is the common pattern among self-hosted platforms (GitLab,
+WooCommerce and BigCommerce all document one), and it does unblock desktop
+clients. But it needs Node, a global install and a hand-edited
+`claude_desktop_config.json` — a developer workflow. Anyone who can do it can
+use the CLI. Packaging it as a desktop extension removes the JSON editing and
+not the install, and reaches one vendor's client only.
+
+**Vendor header features do not deliver it either.** Anthropic's
+`static_headers` lets a merchant paste a key with no terminal, but it is in
+beta behind per-organization gating, carries an open bug where the configured
+header is ignored in favour of an OAuth flow, is an organization-wide
+credential that cannot identify the calling user, and is Anthropic's alone.
+Building the merchant path on it would mean Spree stores connect from Claude
+and from nothing else.
+
+**OAuth is what the clients that matter actually require**, and the spec is
+clear that authorization is optional — so the key-based server is already
+compliant and OAuth is about reach, not correctness. Hosted connectors
+(claude.ai, ChatGPT) fetch the URL from the vendor's own servers, so no local
+process can help them, and OAuth 2.1 is the single interoperable way in.
+
+**Consequences for other work.** The key path stays permanently rather than
+being retired by OAuth; it is how CI jobs, server-side integrations and
+editors authenticate, and commercetools ships both for the same reason. A 401
+on the MCP endpoint is now reserved for an authorization challenge, so
+permission refusals must stay where they already are: `{ error: '…' }`
+inside a 200 JSON-RPC response, which is where MCP puts tool-level failures.
+Promoting one to a 401 would send consumer clients into a re-authorization
+loop. `6.0-platform-auth` phase 7 makes
+Spree an OIDC *client* and does not provide any of this; the two share a spec
+family and almost no code.
+
+## 2026-10-05 — A delegated grant narrows the user's authority; it never inherits it
+
+The OAuth grant an admin approves for an agent carries scopes, and
+`Spree::AgentTools::Context` now takes `granted_scopes:` so those scopes
+intersect with what the user's own role allows. Without the intersection the
+context read only the CanCanCan ability, so a merchant who consented to
+reading products handed over all 64 tools, refunds included.
+
+Two rules the intersection has to keep. It only ever **narrows**: a grant
+naming every key in the catalog still gives a limited role nothing extra, so a
+compromised client cannot widen its own reach. And it applies to record checks
+too, not just to which tools are offered — being handed a read tool is not
+permission to write through it, so `can?` consults the grant before the
+ability.
+
+**Consequences for other work.** Anything that builds a `Context` for a caller
+acting *on behalf of* a person must pass `granted_scopes:`; omitting it means
+the full ability, which is right for the dashboard assistant (the admin is
+acting directly) and wrong for any delegated credential. The MCP endpoint is
+the worked example.
+
+## 2026-10-05 — OAuth lives in spree_api, its tables and models in spree_core
+
+Making Spree an OAuth 2.1 authorization server is platform infrastructure, not
+an MCP detail: `5.5-admin-api-key-scopes` already recorded that a public app
+marketplace would reuse the same scope vocabulary, and merchant-approved
+integrations and storefront customer login are the same flow with a different
+client. So the Doorkeeper configuration sits in `spree_api`, beside the
+authentication it extends, and protected resources register themselves —
+`Spree::Api::Oauth.register_resource(:mcp) { |store| … }` — rather than the
+authorization server knowing about MCP.
+
+The tables and the three models (`Spree::OauthApplication`,
+`OauthAccessGrant`, `OauthAccessToken`, named as they were before 5.4) are in
+`spree_core` for a blunter reason: a migration in `spree_api/db/migrate` is
+only copied by `spree_api:install:migrations`, because the engine names
+differ, while every upgrade guide tells people to run
+`spree:install:migrations`. Left there the tables would silently never be
+created on upgrade. `Spree::ApiKey` is already in core for the same reason.
+
+**Consequences for other work.** `doorkeeper` is a `spree_core` dependency,
+pinned to `~> 6.0.0.rc2` because that is the first release carrying RFC 8707
+resource indicators; relax it to `~> 6.0` once 6.0.0 is final. A new engine
+that needs its own migrations must either live in core or document its own
+install task — do not assume `spree:install:migrations` covers it.
## 2026-10-06 — The products CSV carries each location's shelf count
**Context:** The products export filled `inventory_count` from