# Connecting mcp-znet to Znet's Magento (staging first)

## 1. Create the read-only Integration

In Magento admin (staging): **System › Extensions › Integrations › Add New Integration**

| Field | Value |
|---|---|
| Name | `mcp-znet (read-only)` |
| Email | your email |
| Your Password | your admin password (Magento asks to confirm) |
| Callback / Identity link URL | leave empty |

**API tab** → Resource Access: **Custom**, tick only:

| Admin tree | Used for |
|---|---|
| Catalog › Inventory › **Products** | product sync |
| Catalog › Inventory › **Categories** | category tree |
| Stores › Settings › **All Stores** | store views, locale, currency |
| Stores › Attributes › **Product** | attribute labels/options |
| Stores › Attributes › **Attribute Set** | "missing required attributes" check |
| Sales › Operations › Orders › Actions › **View** | live order tools |
| Sales › Operations › **Invoices** | invoice status |
| Sales › Operations › **Shipments** | shipments + tracking |
| *(only if stock is managed)* Stores › Inventory › **Sources** | stock sync |

Do **not** tick anything that creates, edits or deletes. Save, then **Activate** → **Allow**.
Magento shows four values once: Consumer Key, Consumer Secret, Access Token, Access Token Secret.

## 2. Put them in `.env` (never in chat, email or git)

```
MAGENTO_BASE_URL=https://staging.znet-store.example
MAGENTO_CONSUMER_KEY=…
MAGENTO_CONSUMER_SECRET=…
MAGENTO_ACCESS_TOKEN=…
MAGENTO_ACCESS_TOKEN_SECRET=…
MAGENTO_DEFAULT_STORE=default        # a store view code
CATALOG_STOCK_ENABLED=false          # Znet does not manage stock in Magento
```

All four values are required together — that makes every request OAuth 1.0a-signed, which works on
Magento 2.4.4+ without enabling "integration tokens as Bearer".

## 3. Check before syncing

```bash
pnpm magento:check
```

Every row should be ✅. It prints store view codes (for `MAGENTO_STORE_CODES` /
`MAGENTO_DEFAULT_STORE`), catalog size, and a full-sync time estimate. Common fixes:

| Message | Fix |
|---|---|
| `401 unauthorised` | Integration not activated, or a value mistyped. Re-check all four. |
| `403 — tick "…"` | Add that Resource Access checkbox, save, **Reauthorize** the Integration. |
| `ECONNREFUSED` / `ETIMEDOUT` | Staging not reachable — VPN, or ask Nexcess to allow your IP. |
| Staff sign-in endpoint `not found` | Znet's admins don't use Google Authenticator; tell us which 2FA they use, or `MAGENTO_ADMIN_2FA=none` if 2FA is off on staging. |

The sign-in check uses a random non-existent username, so no real admin account gets locked.

## 4. Sync schedule (defaults)

| Job | Default | Notes |
|---|---|---|
| Changed products | every 2 min | admin saves, API, imports (all bump `updated_at`) |
| Full sweep | hourly at :15 | catches deletions + mass attribute updates; skipped incremental runs while it runs |
| Stores / attributes / categories | hourly at :07 | |
| Stock | off | `CATALOG_STOCK_ENABLED=false` |

If `magento:check` estimates the full sweep at more than ~20 min, move it to nightly
(`SYNC_CRON_FULL=0 2 * * *`) to keep load off Magento.