Start here

Meet Meguro's practice store

Meguro gives your agent a Shopify-shaped practice store with modeled history and a Store clock that moves only inside a run.

Use this when

Use this orientation before your first run or when reviewing a Meguro claim.

Before you start

Choose the agent behavior you want to inspect. Meguro is a simulation environment, not a forecast or certification service.

Steps

Evaluate whether the client can connect to the declared Admin GraphQL surface and make the intended reads or writes.
Inspect observed calls separately from modeled commerce consequences.
Read every not established statement before carrying evidence into a release conversation.

Success looks like

You can state exactly what the agent attempted, what the practice surface accepted or rejected, and what modeled store state changed.

If it fails

Unsupported calls fail loudly. A zero-write run does not establish impact, and a practice receipt does not prove future demand, production performance, certification, or full Shopify parity.

Next action

Continue to Drive your first practice store.

Start here

Drive your first practice store

Create a store with modeled history, connect your agent, and drive it through one bounded simulation. The store hands you a receipt at the end.

Use this when

Use this when you want the shortest path from a new practice store to inspectable evidence.

Before you start

For an MCP agent, open Connection settings and copy the agent instruction. Approve access when it asks. For an existing Shopify Admin client, use the steps below.

Steps

Create a practice store. Choose a scenario for the job you want your agent to handle and read its brief.
Confirm connection with one authenticated read. Point the client at the store Admin URL and token.
Start a run. Choose who controls Store time and open the observation window.
Run the agent. Have it carry out the scenario's brief through the planned Store days, using the clock you chose.
Open the receipt. Review recorded behavior, modeled change, and proof boundaries.

Success looks like

The receipt opens with the expected store, agent/run identity, recorded calls, and an explicit evidence boundary.

If it fails

If the first read is not recorded, stop: recheck the Admin URL, send the whole per-store token as X-Shopify-Access-Token, and retry the read before starting another run.

Next action

Open Meguro and create a practice store.

Start here

When not to use Meguro

Meguro is deliberately narrow. It is the wrong tool when:

Scope and proof boundaries

You need proof of live performance. Receipts are rehearsal evidence from a simulated store — not forecasts, certifications, or evidence of market demand. Meguro says this in-band because it's true.

Your critical path lives outside the modeled subset. Meguro models a subset of the Shopify Admin API and refuses the rest with a teaching error rather than faking behavior. If the calls your app depends on aren't in the modeled subset — the refusal enumerates it, and the compatibility table lists it — Meguro cannot exercise them, and won't pretend to.

You're testing storefront pages, themes, or checkout UI. A practice store renders no pages. It serves two agent surfaces: the Admin-shaped API, and a shopper endpoint that models Storefront reads, cart, and a checkout that ends at the buyer handoff. Payment placement is out.

You're load-testing. Meguro models Shopify's request cost bucket, so throttling and backoff show up on the receipt. It measures no latency or capacity and benchmarks nothing.

Your agent only reads. If it reads a catalog once and writes nothing, a fixture file is cheaper. An agent that writes gets a full receipt without moving Store time. Time matters only for modeled consequences.

You want someone to run your agent for you. Meguro never executes your agent; it provides the store and the record. Bring your own agent — that's the design, not a gap.

Connect and run

Choose a practice store

Match the store and scenario to the agent job before you start collecting evidence.

Use this when

Use this when selecting a practice store for pricing, inventory, fulfillment, retention, or catalog work. Return/restocking, loyalty-credit, cohort, and cross-location transfer economics are internal modeled evidence, not provider operations to send.

Before you start

Read the scenario's brief and check that it matches the job you want your agent to handle.

Steps

Pricing or promotion: choose demand and margin pressure with supported Product or variant price actions.
Inventory: choose low-stock or replenishment pressure.
Order cash refund: choose a canonical committed order with priced committed lines. Return and restocking economics stay internal modeled evidence.
Fulfillment: choose backlog, SLA, or shipping-threshold pressure.
Retention: choose modeled winback or abandoned-checkout pressure. Cohort, loyalty-credit, and response economics stay internal modeled evidence; no Shopify transaction-discount action is served.
Catalog: choose launch, metadata, bundle, or subscription-plan work.

Agent job	Modeled pressure	Meaningful actions to exercise
Pricing	Demand and margin response	Product and variant price changes
Inventory	Stockouts and incoming supply	Adjust available inventory at one location
Order cash refund	Canonical committed order with priced committed lines	Issue a line-item cash refund; inspect separately labelled return/restocking evidence
Fulfillment	Backlog and delivery thresholds	Fulfill an order or adjust a delivery profile
Retention	Modeled winback or abandoned-checkout pressure	Analyze modeled response evidence; no Shopify transaction-discount action is served
Catalog	Launch and content quality	Update product data, variants, or product-owned metafields

Success looks like

The scenario's brief matches your agent's job, and the required calls are supported.

If it fails

If a required call is unsupported, record the gap. Choose another scenario only if its brief still matches the job you need to rehearse.

Next action

Continue to Connect an existing Admin client.

Connect and run

Connect your agent over MCP

Connect your own agent to Meguro’s hosted MCP server, approve access, and choose a practice scenario.

Use this when

Use this when your agent speaks MCP. Meguro runs one hosted server; there is no Meguro package to install or local Meguro STDIO server to start.

Before you start

Use this hosted endpoint, including /mcp: https://mcp.meguro.io/mcp.

Have a Meguro account, or create one during browser sign-in. Your first run costs nothing. The automatic sample does not bind your included evaluation; the first accepted run on a customer-chosen template store binds it to that Store and its planned Store-day horizon; explicit continuations through its remaining included days consume no monthly run; after the root ends, a plain start replays the same Store days as a new run and spends one monthly run.

Browser consent and permissions

Sign in and approve only the requested access. Every browser approval creates a fresh grant; reconnecting does not replace or revoke older grants. The consent screen names the permissions it requests:

View your practice stores
Create and delete practice stores
Read practice runs and receipts
Start, advance, finish, and clean up practice runs
Read store connection tokens

Workspace API key alternative

Clients that support authorization headers can use a workspace API key instead of OAuth. Create it in Console → Settings → Connection and configure Authorization: Bearer <workspace API key> in the client’s protected credential or header settings. The key remains bound to its workspace. Do not use a per-store Admin token, paste browser tokens or cookies, or put a key in a launch command, receipt or support message.

Steps

Claude.ai connectors

In Claude.ai, open Customize → Connectors, select + → Add custom connector, enter https://mcp.meguro.io/mcp, and select Add. On Team or Enterprise, an owner first adds the Web custom connector in Organization settings → Connectors; members then select Connect.
Connect and complete Meguro’s browser sign-in and consent. In a conversation, open + → Connectors and enable Meguro.

Official Claude connector instructions.

Claude Code

Run claude mcp add --transport http meguro https://mcp.meguro.io/mcp.
Open Claude Code, run /mcp, select Meguro and complete browser authentication. Confirm it is connected before asking it to act.

Official Claude Code instructions.

Cursor

Select Add Meguro to Cursor, then review and accept Cursor’s server-install prompt. The link configures the same hosted endpoint shown above.
Complete browser authentication when prompted and enable the server for your agent.

Official Cursor install-link instructions.

ChatGPT web

Open Settings → Security and login and enable Developer mode. Availability depends on your account and workspace policy.
Open Plugins, select +, enter the name Meguro and a description, and enter https://mcp.meguro.io/mcp under Connection as a public MCP server URL. Create the connection and complete browser consent.
Start a new conversation and add the MCP connection from the tools menu.

Official ChatGPT connection instructions.

Codex and the ChatGPT desktop app

For the CLI, run codex mcp add meguro --url https://mcp.meguro.io/mcp, then codex mcp login meguro and complete browser consent.
Alternatively, in the desktop app open Settings → MCP servers → Add server, name it Meguro, select Streamable HTTP and enter https://mcp.meguro.io/mcp. Save, select Restart, then Authenticate. The desktop app, CLI and IDE extension share the host’s MCP configuration.

Official Codex and desktop instructions.

Compatibility bridge

If your client accepts only a command, configure npx -y mcp-remote https://mcp.meguro.io/mcp as its MCP launch command and complete browser consent. This is a third-party bridge to the hosted server, not a local Meguro server. Prefer the direct URL when your client supports it. Bridge instructions.

Success looks like

The client lists Meguro’s tools. Ask it: “Choose a practice scenario, read its brief, and do what the brief asks. Bring me back the receipt link.” It should read the server-owned scenario and run plan before starting.

If it fails

If authentication fails, confirm the endpoint includes /mcp and reconnect through your client’s authentication control. Reauthorization creates a fresh grant; revoke any older grants you no longer want. A client that lacks remote HTTP support needs the compatibility bridge above.

Next action

Review and revoke access at Console → Settings → Connection → MCP authorizations. Revocation stops refresh immediately; an issued access token can remain valid for up to 15 minutes. Remove the connection in your client separately to clear its local configuration.

Connect and run

Connect an existing Shopify Admin client

Keep the client you already use; change only its Admin URL and per-store token.

Use this when

Use this when connecting a Shopify Admin GraphQL client to one practice store.

Before you start

Create the store first. Keep the workspace API key separate from the per-store Admin token.

Steps

Open the store’s Connect view and copy its Admin GraphQL URL and per-store Admin token.
Set the client’s Admin endpoint to that URL and send the token as X-Shopify-Access-Token.
Send one authenticated read such as a shop identity query. Reads work before a run.
Wait for Meguro to record the first call, then start the run before sending writes.

Success looks like

The connection listener records the read against the intended store without exposing either credential in a receipt.

If it fails

What happened: no read appeared. What it means: the process may be using a different URL or clipped token. What to do next: copy both fields again, confirm the header, and retry one read. Writes outside an active run are rejected.

Next action

Choose how Store time moves, or open Stores and re-enter this store’s Overview.

Connect and run

Choose Store time

Pick Manual or Scheduled Store time for your run.

Use this when

Use this when starting a run that needs modeled events over time and you must choose its store clock.

Before you start

Time moves as your run drives it. Choose Manual when you need an explicit advance, or Scheduled when the next qualifying run request should materialize elapsed Store time.

Steps

Mode	Control	Use it when
Manual	You explicitly advance Store time	You want to inspect each boundary before moving on
Scheduled	The next qualifying run request materializes elapsed Store time	You want elapsed time to catch up as your run continues

Success looks like

The active run displays its chosen clock, current modeled day, and next allowed action.

If it fails

If a Manual advance is rejected, refresh the run state and copy its fresh practiceRun.advanceCursor object unchanged. Scheduled time does not advance an idle run in the background.

Next action

Continue to Exercise and finish a run. In Meguro, select the store and continue from its Overview or Runs tab.

Connect and run

Exercise and finish a run

Have your agent carry out the scenario's brief through the planned Store days, then inspect the receipt.

Use this when

Use this after a read has confirmed connection and the run is active.

Before you start

Read the scenario's brief and run plan. Check that the required calls are on the supported Admin GraphQL surface.

Steps

Have your agent carry out the scenario's brief.
Inspect which calls were accepted, rejected, or unsupported, and what state changed.
Time moves as your run drives it. In Manual mode, explicitly advance time; in Scheduled mode, elapsed time is materialized on the next qualifying run request.
At the planned end, follow the run's completion instructions and open the receipt. If the run needs to stop early, cancel it and review the partial evidence.

Success looks like

The concluded receipt distinguishes accepted calls, blocked calls, state deltas, and empty or partial evidence.

If it fails

A zero-write simulation run does not establish impact. Cancellation preserves evidence already recorded; infrastructure start failures or runs with no agent execution do not consume a simulation run.

Next action

Open Read the current receipt.

Understand the result

Read the current receipt

Interpret the customer hierarchy first, then move into evidence and developer details.

Use this when

Use this for any concluded receipt before sharing it or evaluating it with a Configured Receipt Gate.

Before you start

Read the receipt’s sealed conduct Gate first. Go requires a completed run with recorded agent execution, no unresolved rejected call, and no failed or inconclusive exercised declared check. Stopped and empty runs are no-go; an unexercised declaration is neutral. Modeled outcome and money are separate facts. Confirm the store, scenario, seed, declared agent subject, client API target, execution environment, live verification state, and exercised operation scope. Customer-declared build identity is not independently verified by Meguro.

Steps

Read the Gate sentence for the sealed conduct decision, then Goal outcome for the separate modeled result.
Read Lane integrity for whether the run stayed inside the declared execution lane.
Read Footprint for calls, accepted and rejected writes, and modeled changes.
Inspect the Decisive moment and Next technical proof.
Use Evidence for reviewable facts and Developer details for protocols and debugging.
Classify claims as Observed, Modeled, or Not established.

Success looks like

You can trace the result to recorded calls and explicitly bounded modeled consequences without upgrading simulation evidence into production proof.

If it fails

If the evidence is partial, identify the missing proof layer: agent contact, representative write, state delta, scenario source, or completion. Do not replace missing evidence with inference.

Next action

Continue to Apply the proof boundaries, or select the store and reopen its Runs tab.

Understand the result

Share, retain, and verify receipt integrity

Verify artifact integrity without implying that a digest verifies the receipt’s result.

Use this when

Use this before sharing or retaining receipt evidence.

Before you start

Choose the customer-safe artifact and check its visibility, issuance time, and receipt-availability window.

Steps

Download or copy the bounded artifact from the product.
Retain it within your plan’s availability window or in your own controlled evidence store.
Recompute the documented artifact digest to verify bytes and detect alteration.
Review the evidence and proof-boundary text separately; digest validity does not validate the result.

Success looks like

The artifact bytes match their digest and the reviewer can identify what was observed, modeled, and not established.

If it fails

If the receipt is no longer fetchable, use a previously retained artifact. Never infer a result from an id or digest alone. Practice receipts do not prove future demand or full Shopify parity.

Next action

Use Configured Gate and automation to project the same sealed decision in CI.

Automate

Automate a practice run

Run the same bounded lifecycle from CI or hosted MCP without repository-only steps.

Use this when

Use this when the five-step practice loop must run repeatably outside the dashboard.

Before you start

Create a workspace API key for direct API calls, or authorize hosted MCP with OAuth. Keep control credentials out of the agent process; the agent receives only the store Admin URL and token.

Steps

Package-free CI: call the documented practice HTTP endpoints with your existing HTTP client; preserve failed artifacts and return a CI exit code owned by your policy.
Hosted MCP: connect with OAuth 2.1 to stateless Streamable HTTP /mcp. Clients without remote transport support can bridge to the hosted URL with npx -y mcp-remote <hosted MCP URL>; configure OAuth or a workspace key as standard Bearer authorization, never as a process argument.
Start, inspect status, capture checkpoints when needed, copy practiceRun.advanceCursor unchanged into advance, finish or cancel, and fetch the receipt.

Success looks like

Automation emits only copyable or downloadable artifacts, preserves the full receipt boundary, and never passes the workspace key to the agent under test.

If it fails

If a control call fails, record its status and bounded response, refresh status for the server-owned practiceRun.advanceCursor, and stop rather than manufacturing a successful artifact. The shopper-facing practice-store /api/mcp is a separate Storefront data plane, not the hosted control plane.

Next action

Add a Configured Gate signal for the concluded receipt; keep any money threshold in your own CI step.

Automate

Use the configured conduct Gate

The configured Gate projects the selected receipt’s sealed conduct decision; it does not decide whether you should ship.

Use this when

Use this when CI or Console should read the same Gate decision already sealed with a concluded run receipt.

Before you start

Choose the Store and receipt. Conduct Gate needs no caller-defined criteria or policy version. Keep a modeled-money threshold separate and customer-owned.

Before a secret-bearing CI job, download Meguro CI kit v1 from the public marketing site, verify its pinned SHA-256, unpack it as byo-ci-test/, review it, and commit that directory. CI runs the vendored files; it never downloads executable code after secrets are supplied.

curl -fsS -o meguro-ci-kit-v1.tar.gz https://meguro.io/downloads/meguro-ci-kit-v1.tar.gz
curl -fsS -o meguro-ci-kit-v1.tar.gz.sha256 https://meguro.io/downloads/meguro-ci-kit-v1.tar.gz.sha256
printf '%s  %s\n' 'c63478ff109ee382cf2fb114d975a8bdcc8ff01aab52562ae45f6a799d9e1a5f' 'meguro-ci-kit-v1.tar.gz' | cmp - meguro-ci-kit-v1.tar.gz.sha256
shasum -a 256 -c meguro-ci-kit-v1.tar.gz.sha256
tar -xzf meguro-ci-kit-v1.tar.gz
git add byo-ci-test/

Steps

Select one Store and its concluded receipt.
Read or evaluate the configured Gate; the response carries policy meguro.release-gate-policy.v2 and the receipt’s own go/no-go sentence.
Fail CI when the Gate is no-go. If your business rule also requires nonnegative net contribution, add a separate command that checks the receipt’s modeled value.
Retain the receipt and Gate evaluation together so the decision remains traceable.

Success looks like

The configured response and the receipt display one conduct decision. Modeled outcome, catalog source, and money remain separate facts; you own the release decision.

If it fails

If the run has not concluded, the Gate is transiently waiting. A sealed receipt is go or no-go, never waiting.

Next action

An Exam answer transcript is separate and is not a Configured Receipt Gate evidence source. To continue in Meguro, select the store and open its Configured Receipt Gate tab.

Verify on Shopify

Verify with Shopify Exam

The Exam replays the recorded requests on your Shopify development store and records Shopify's answers.

Use this when

Use Shopify Exam when you need Shopify’s recorded answers for requests from one Practice run.

Before you start

The Exam proves only what Shopify returned for those recorded requests on that development store. It does not decide whether the agent was right. Target-store state can differ from the Practice world, especially for calls recorded after the Practice clock first advanced.

Steps

Confirm the Shopify development store and the recorded requests to replay.
Use the shared call index to line up the Practice record with Shopify’s answer transcript.
accepted means Shopify answered without GraphQL or user errors; rejected means Shopify answered with errors; no-answer means Meguro cannot determine Shopify’s answer after a send.
When the source ledger contains webhook creation, read this disclosure before replay: “A webhook subscription in this transcript points at the agent's callback URL from the run. Shopify sends development-store events there until the ledger's delete call or the customer removes it.”
Preparation restores Meguro’s canonical baseline, preserves customer-owned and earlier Exam-tagged objects, and has no cleanup phase.

Success looks like

Exact Shopify and Practice request/response material stays private. The public transcript is redacted and capability-addressed.

If it fails

A no-answer does not establish a Shopify result. An Exam does not establish whether the agent was right, production safety, future demand, or complete Shopify compatibility.

Next action

Carry only the transcript’s recorded Shopify answers into your next review. Exam is not a Configured Receipt Gate evidence source.

Account and billing

Plans, simulation runs, and limits

Pricing and capacity follow the enforced Free, Solo, and Builder contracts.

Use this when

Use this when choosing a plan or interpreting Usage.

Before you start

A no-card 14-day Solo trial lands on permanent Free. Read simulation run and simulation canvas before comparing limits.

Steps

Plan	Price	Simulation runs / month	Canvas	Receipt availability	Active stores	Active workspaces
Free	$0	10	14 world-days	7 days	1	1
Solo	$60/month or $600/year	30	30 world-days	90 days	1	1
Builder	$199/month or $1,990/year	100 included	30-day runs can continue one aging store to 365 world-days	365 days	3	10

Success looks like

Usage shows reserved, charged, released, remaining, and overage simulation runs under the current plan. Every tier receives the same receipt truth; plans change capacity, not evidence quality.

If it fails

Free and Solo stop the exact over-limit action before work begins and name the limit; existing stores and evidence remain readable. Builder records usage beyond 100 included simulation runs, but automated overage invoicing is not enabled at launch. Archiving a store or workspace can release its active slot.

Next action

Open Usage or public pricing.

Account and billing

Credentials and connections

Use each credential only for its declared target and rotate it when exposure is possible.

Use this when

Use this when connecting an external tool, CI job, MCP client, or Shopify Admin client.

Before you start

Distinguish the workspace API key from the per-store Admin token. Real credential values must never enter Documentation, receipts, support messages, or logs.

Steps

Workspace API key: begins meg_sk_…, is shown once, and scopes an external control client to one workspace. Put it in MEGURO_API_TOKEN.
Per-store Admin token: begins meg_pw_…, targets one practice store, and is sent by the agent as X-Shopify-Access-Token.
Hosted control plane: OAuth 2.1 remote MCP over stateless Streamable HTTP /mcp, with workspace API keys accepted as Bearer authorization.
Without signing in, hosted MCP supports initialization, lists the complete tool catalog, and serves docs_read; only docs_read is callable without authorization, and all other tools require OAuth.
Compatibility bridge: clients without remote transport support can use mcp-remote to reach the hosted MCP URL.
Separate shopper plane: a practice store’s /api/mcp endpoint models Storefront shopper interactions and does not replace the control plane.

Success looks like

The external control client is limited to its workspace, while the agent under test can reach only the intended practice store.

If it fails

An invalid or revoked workspace key must be replaced in Connection settings. Rotate credentials after possible exposure and update every intended client; never paste Cognito tokens, browser cookies, or browser storage into a terminal.

Next action

Open Connection settings.

Account and billing

Workspaces, deletion, and support

Separate customer evidence by workspace and use owner-only deletion when an account must be removed.

Use this when

Use workspaces to isolate stores, runs, keys, members, and evidence for different customers or operating contexts.

Before you start

Check your active-workspace limit: Free and Solo allow 1 including Default; Builder allows 10.

Steps

Create or select the intended workspace before creating stores and keys.
Archive an inactive workspace to release its slot; restoring it rechecks the current limit.
For account deletion, use the owner-only account settings flow. Deletion revokes workspace keys first and cancels an active subscription without issuing an automatic refund.

Success looks like

The selected workspace owns its stores, runs, receipts, members, and keys without cross-workspace credential reach.

If it fails

If a workspace or deletion action is unavailable, confirm owner/member role and the active limit. For unresolved account or billing issues, contact hello@meguro.io without sending credentials.

Next action

Open Workspaces or Account settings.

Reference and troubleshooting

Store and scenario catalog

Choose by agent job first, then use the store detail to inspect the exact entities and modeled pressure.

Scope and proof boundaries

Catalog entries declare modeled commerce conditions; they are not forecasts or claims about future customer demand. A template does not redefine the globally supported Admin GraphQL surface. Scenario-only launch-candidate state, carrier-expedite consequences, and variant discontinuation are modeled or reference-only; do not treat them as Shopify read or write capabilities. productUpdate(status: ARCHIVED) affects a whole product, not a variant.

Choose by agent job

Agent job	Look for	Representative evidence
Pricing	Products with margin and demand sensitivity	Price or discount change plus modeled demand and contribution
Inventory	Low stock or incoming supply	Single-location adjustment plus modeled stock position
Order cash refund	Canonical committed order and priced committed lines	Line-item cash refund plus separately labelled return/restocking evidence
Fulfillment	Open fulfillment work or shipping thresholds	Fulfillment progress or delivery-profile consequence
Retention	Abandoned checkout or discount pressure	Bounded offer plus separately labelled modeled cohort or loyalty evidence
Catalog	Modeled launch pressure, quality gaps, bundles, or plans	Product-owned catalog change and accepted call record

Inspect the selected store

The store detail is authoritative for its scenario label, seed, starting modeled day, entities, pressure, and suggested meaningful actions. Use Supported Admin GraphQL surface to verify the call shape separately.

Reference and troubleshooting

Canonical definitions

Each product term is defined once here; task articles link to these anchors.

Scope and proof boundaries

These definitions describe Meguro’s current public product contract. They do not expand a practice receipt into production, forecasting, certification, or full-platform proof.

Definitions

Term	Authoritative definition
Practice store	A deterministic Shopify-shaped environment with a declared Admin GraphQL surface, modeled commerce behavior, and an explicit scenario and seed.
Store clock	The declared control of modeled store time for a run: Manual or Scheduled. Time moves as your run drives it.
Run	One bounded observation window in which an agent acts against one practice store and Meguro records calls and state changes.
Receipt	The immutable review artifact for a concluded run: recorded calls, accepted or blocked actions, modeled state changes, proof boundaries, and integrity metadata.
Simulation run	One execution for one agent version, one store, one scenario, and one seed; a failure can be the honest result when agent execution occurred.
Simulation canvas	The maximum modeled world-time available to one simulation run or continuation chain under the active plan.
Observed	Directly recorded from the agent interaction or target system during this run.
Modeled	Computed by Meguro’s declared practice-store model from recorded inputs and actions.
Not established	A claim the available evidence does not prove and must not imply.
Conduct Gate	The sealed receipt’s go or no-go decision about completed recorded agent execution, unresolved rejected calls, and exercised declared checks. A configured Gate displays that same decision for a selected Store and receipt; the user owns any release decision.
Shopify Exam	A replay of recorded requests that records Shopify’s answers on one development store. It does not decide whether the agent was right.
Workspace API key	A one-time-shown credential beginning meg_sk_ that authenticates an external tool to one workspace.
Per-store Admin token	A credential beginning meg_pw_ that targets one practice store through its Shopify-shaped Admin endpoint.

Reference and troubleshooting

Supported Admin GraphQL surface

The declared Shopify-shaped Admin surface and its loud boundaries.

Scope and proof boundaries

This is a practice surface, not a claim of full Shopify parity. Help names three states: served v1 provider operations, internal modeled evidence, and deferred v2. Supported fields and shapes are bounded; unsupported calls return GraphQL errors or userErrors rather than fake success.

Supported query roots

Roots	Use
`shop`, `node`, `nodes`	Shop identity, global-id readback, and object hydration
`products`, `product`, `productByHandle`, `productVariants`, `inventoryItems`	Catalog, variants, pricing, inventory, cost, status, tags, SEO, and product-owned metafields
`orders`, `order`, `draftOrders`, `draftOrder`	Canonical committed orders, priced line items, financial and fulfillment state, risk, refunds, and bounded drafts
`customers`, `customer`, `segments`	Read-only lifecycle, repeat-buyer, and winback context; no persistent customer membership operation
`locations`, `fulfillmentOrders`, `deliveryProfiles`	Inventory location, fulfillment, and delivery evidence

Supported mutation families

Family	Use	Modeled consequence
`productVariantsBulkUpdate`	Pricing	Price and compare-at values can affect modeled demand and margin
`inventoryAdjustQuantities`	Inventory	Truthful available-inventory adjustment at a single location; no cross-location transfer operation
`refundCreate`	Order refunds	Line-item cash refund only against a canonical committed `Order` and its priced committed lines. `NO_RESTOCK` and `RETURN` are the restock choices. `RefundInput.transactions`, `RefundInput.refundMethods`, and `Customer.storeCreditAccounts` are absent.
`fulfillmentCreateV2`, `deliveryProfileUpdate`	Fulfillment	Fulfillment progress and shipping-threshold effects
`productBundleCreate`, `sellingPlanGroupCreate`	Bundles and plans	Native creation and official readback; attach, churn, and money remain modeled scenario effects
`draftOrderCreate`, `draftOrderComplete`	Order staging	Only `draftOrderComplete` establishes a canonical committed order. The shopper surface serves UCP general access and places none: a checkout there ends at a buyer handoff
`productUpdate`, `metafieldsSet`	Catalog	A preauthored DRAFT product activates through `productUpdate(status: ACTIVE)`; product-owned metadata remains supported

Meguro-native debugging extensions

productBundleCreate returns an asynchronous product operation; read it through productOperation(id). sellingPlanGroupCreate returns a selling-plan group; read it through sellingPlanGroup, sellingPlanGroups, and nested SellingPlanGroup.sellingPlans. The former fake bundle/subscription roots are absent. Remaining Meguro-native lifecycle extensions are not ordinary Shopify Admin roots or proof of Shopify support. Attach, churn, and money are modeled scenario outcomes, not Shopify response fields.

Internal modeled evidence

Return/restocking, loyalty-credit, cohort, and cross-location transfer economics are internal modeled evidence. They are not a request shape, provider mutation, provider readback, or provider identity.

Deferred v2

The provider Return lifecycle, collection curation, gift cards, product creation, persistent customer membership, aggregate-order economics, and store-credit refunds are deferred v2. Current v1 has no provider operation or substitute for them.

Known boundary

Absolute inventory-set writes, broad order edits, pending-payment draft completion, generic payment lifecycle, bulk operations, broad productSet, non-product metafields, carrier APIs, and native checkout completion are outside the current declared practice contract.

Reference and troubleshooting

API reference

Public control, receipt, and schema contracts.

Scope and proof boundaries

These identifiers and routes are legitimate public integration material. A customer run controls one bounded practice lifecycle; it does not grant Shopify production access or verify a receipt result.

Identity and credentials

storeId identifies the practice store; worldId remains an accepted compatibility alias.
attemptId identifies the run returned by start and is used by later lifecycle calls.
Control calls use the workspace API key; the agent receives only the separate Admin URL and per-store token.

Run lifecycle

Action	HTTP route	MCP tool
Start	`POST /practice/stores/{storeId}/playbacks`	`practice_run_start`
Status	`GET /practice/playbacks/{attemptId}/state`	`practice_run_status`
Checkpoint	`POST /practice/playbacks/{attemptId}/checkpoint`	`practice_run_checkpoint`
Advance	`POST /practice/playbacks/{attemptId}/advance`	`practice_run_advance`
Finish	`POST /practice/playbacks/{attemptId}/finish`	`practice_run_finish`
Receipt	`GET /practice/playbacks/{attemptId}/report`	`practice_run_report`

Advance accepts exactly one of days or until. Copy the current server-owned practiceRun.advanceCursor object unchanged; legacy flat expectedDay and expectedCallSeq request fields remain compatible.

Schemas and artifacts

What it usually means

The account may still be waiting for a signed payment update, the action may require the account owner, or the current subscription state may keep Free limits in effect.

What to do next

Open Plans and billing as the account owner. After a delayed return, use Check again once and do not submit Checkout again while confirmation is pending. Use Manage billing for the current subscription or contact support if the signed update remains missing.

What to include for support

Include the account email, route, selected plan and interval, timestamp and timezone, exact visible billing text, and whether it persists after reload. Never send card details, checkout URLs, credentials, or payment secrets.

Reference and troubleshooting

Contact support

Escalate an unresolved Documentation problem with enough customer-safe context to investigate it.

Scope and proof boundaries

Support context should identify the visible customer-facing failure without exposing secrets, private payloads, customer data, or internal implementation details.

Contact support

Email hello@meguro.io after completing the relevant troubleshooting step. There is no need to send a private diagnostic bundle.

What to include

Your account email.
The route where the problem appears.
The visible store, run, or receipt ID when available.
The timestamp and timezone.
The exact visible error text.
Whether the issue persists after reload.

What never to send

Never send access tokens, API keys, credentials, authorization headers, private request payloads, secrets, or customer PII/data. Remove those values before sending any screenshot or copied text.