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.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Documented connecting an agent by signing in
Damian Legawiec043e140d739e
diff --git a/docs/developer/agentic/admin-mcp.mdx b/docs/developer/agentic/admin-mcp.mdxindex 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 theGive 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 keyThe 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 alsodiff --git a/docs/plans/6.0-mcp-oauth.md b/docs/plans/6.0-mcp-oauth.mdnew file mode 100644index 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/5262diff --git a/docs/plans/6.0-mcp-server.md b/docs/plans/6.0-mcp-server.mdindex 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.## Referencesdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 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 anywebhook endpoint, whatever it subscribes to — the rule 5.x kept in thesubscriber'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