Magento 2 / Adobe Commerce

In Magento Admin, go to System → Extensions → Integrations → Add New Integration. Give it a descriptive name like ShopMCP. You can leave Callback URL and Identity Link URL blank — ShopMCP does not use the OAuth handshake flow, only the Access Token.

Switch to the API tab. The resource tree on this screen is the only thing standing between ShopMCP and your whole store, so take a minute to scope it properly. Below is the recommended read-only scope that activates every v1 Magento tool ShopMCP ships:

• Catalog → Inventory → Products — read
• Catalog → Inventory → Categories — read
• Catalog → Inventory → Manage Stock — read (covers both legacy stockItems and MSI source-items)
• Sales → Operations → Orders — read
• Sales → Operations → Invoices — read
• Sales → Operations → Shipments — read
• Sales → Operations → Credit Memos — read
• Customers → All Customers — read
• Marketing → Promotions → Cart Price Rules — read (optional; enables magento_get_sales_rules and magento_get_coupons)
• Stores → Settings → All Stores — read
• System → Other Settings → Modules — read (enables magento_store_status)

Click Save. Back on the Integrations list, click Activate next to the row you just created. Magento will show the Access Token once — copy it immediately. If you lose it, click Reauthorize to mint a fresh one.

Open Settings → Integrations → Magento and fill in:

• Store base URL — e.g. https://store.example.com. No trailing slash, no /rest/V1, no admin path. ShopMCP appends /rest/V1 internally.
• Integration access token — the token from step 3

On submit, ShopMCP calls GET /rest/V1/store/storeConfigs to confirm the token is activated and has at least minimal read ACL. A successful verification persists the credentials encrypted-at-rest (KMS envelope) and flips the Magento module to Connected for every API key in the workspace.

ShopMCP's Magento package includes six write tools — magento_update_product, magento_update_customer, magento_update_order_status (hold / unhold / cancel only), magento_add_order_comment, magento_create_invoice, and magento_create_shipment. These are compiled in but never registered in v1. The runtime calls registerMagentoTools({ allowWrites: false }) regardless of plan tier.

Each write tool is locked to a hand-written, field-level input allowlist. For example, magento_update_product accepts name, price, special_price, status, visibility, description, short_description, weight, qty, is_in_stock — and nothing else. SKU rename, attribute_set_id, website_id, and bulk custom attribute replacement are all rejected at the input schema layer before any HTTP request is built. This is deliberate: if a prompt injection convinces the LLM to call the tool with disallowed fields, the Zod validator drops the request on the floor.

When writes are turned on for your workspace (later), you'll also need to widen the Magento-side ACL to grant the matching write scopes. The minimum is documented in packages/magento-mcp/docs/magento-kb/recommended-acl-scope.md and mirrored inside the magento_help_search tool.

• Rotate every ~90 days. In Magento Admin, open the ShopMCP integration row and click Reauthorize. Magento issues a new token. In ShopMCP, disconnect the existing connection and reconnect with the new token — no data is lost, the connections row is rebuilt in place.
• Revoke instantly. Delete the integration in Magento Admin. ShopMCP's next tool call will receive HTTP 401 and surface "Magento rejected the access token" to the user.
• Disconnect from ShopMCP. Click Disconnect on the Magento connect page. This removes the connections row and disables the workspace_modules toggle but does not touch the Magento-side integration — delete it there as well if you want a full revoke.

• Scope the Integration tightly. Only tick the resources the tools you actually use require. Re-audit quarterly.
• Put a WAF in front of your Magento store — ShopMCP calls the REST API from fixed egress IPs you can allowlist.
• Turn on Magento 2FA for admins. Unrelated to the ShopMCP connection but reduces the blast radius of a stolen admin session.
• Audit /settings/api-keys usage weekly. Every Magento tool call writes a row to usage_events with the tool name and status — unusual spikes are worth investigating.
• Start read-only. v1 is read-only by default; resist the urge to patch the runtime flag before you understand the blast radius.
• Train your team on prompt injection. Treat any text that came from outside the company — support emails, product reviews, shipping-label comments — as potentially hostile when you paste it into chat alongside a Magento tool call.

• "Magento rejected the access token" (401) — the integration is deactivated or the token was rotated. Reactivate / reauthorize in Magento Admin and reconnect in ShopMCP.
• "Magento's Integration ACL forbids this resource" (403) — the tool you called needs a scope the integration's ACL doesn't have. Open the integration in Magento Admin, widen the ACL by exactly one resource, save, and retry. No reconnect needed.
• "Magento returned 404 for /rest/V1/store/storeConfigs" during the connect verify step — the base URL is wrong. It should be the storefront host, not the admin path. Drop any /admin or /rest/V1 suffix.
• "Magento is rate-limiting" (429) — the store's REST API is throttling. ShopMCP does not retry automatically on 429 by design. Wait the duration in the error message and try again.
• Tool returns a confusing upstream error — call magento_help_search with keywords like "search criteria" or "order status" to get the ShopMCP KB explanation of what Magento expects.