meguro-mcp — the control plane for your AI tools

Drive Meguro worlds from Claude Code, Cursor, or any MCP client: start a run that writes months of believable history onto a real dev store, or orchestrate an external agent against a tenant-owned practice store and collect bounded receipt evidence.

This is the control plane (world/run management, for the developer's tools). It is not the data plane (the practice-lane Shopify facade the agent under test talks to).

Dependency-free, no build step: the server is plain Node ≥ 20.

Recommended: hosted Streamable HTTP + OAuth

For an interactive client that supports Streamable HTTP and browser OAuth, open Meguro Console → Settings → Connection and copy the hosted MCP URL for that environment. Add it as a Streamable HTTP MCP server, save or restart if the client asks, then choose Authenticate. Your browser opens so you can sign in to Meguro and authorize the requested access. The default path needs no API key, environment variable, package command, or pasted token.

The configured hosted endpoints are environment-specific: dev uses https://mcp-dev.meguro.io/mcp, stage uses https://mcp-stage.meguro.io/mcp, and production uses https://mcp.meguro.io/mcp. Use the URL shown by the Console for the environment you intend to access.

After connecting, read meguro://docs/getting-started/v13 for the world-first operating sequence; for general Meguro questions, read meguro://docs/product-guide/v10. Both are available through resources/read or the matching docs_read({ topic, version }) fallback.

The hosted server exposes 39 customer-safe tools and deliberately excludes admin_probe. Active grants are visible and revocable under Console → Settings → Connection → MCP authorizations.

Transport boundaries

The public package speaks newline-delimited JSON-RPC over stdin/stdout and uses MEGURO_API_BASE_URL plus MEGURO_API_TOKEN for its authenticated HTTP calls. It is the local/CI fallback, separate from the hosted Streamable HTTP OAuth endpoint.

Practice stores separately expose a Storefront shopper/data-plane MCP endpoint at https://<worldId>.meguro.io/api/mcp. That endpoint is not this server and cannot start runs, reveal Admin connection details, inspect schemas, or collect receipts.

Console provides fast trusted proof and evidence inspection; the agency agent normally remains in its own environment. A practice-store endpoint/token remains stable while commerce time moves through explicit run tools. Practice evidence is deterministic scenario simulation, not merchant forecasting. Console-proof actions are not credited to the agent, and Receipt Gate evidence is not public certification.

Tools

This table is generated from the server's live tools/list response (48 tools).

| Tool | Title | Behavior annotations | |---|---|---| | docs_read | Read Meguro product and evidence documentation | read-only · non-destructive · idempotent · closed-world | | templates_list | List practice-store templates | read-only · non-destructive · idempotent · closed-world | | stores_list | List practice stores | read-only · non-destructive · idempotent · closed-world | | store_create | Create a practice store | read-write · non-destructive · non-idempotent · closed-world | | store_delete | Delete a practice store | read-write · destructive · non-idempotent · closed-world | | store_passport | Read Store Passport | read-only · non-destructive · idempotent · closed-world | | workspaces_list | List account workspaces | read-only · non-destructive · idempotent · closed-world | | workspace_create | Create a workspace | read-write · non-destructive · non-idempotent · closed-world | | workspace_archive | Archive a workspace | read-write · destructive · idempotent · closed-world | | workspace_unarchive | Restore a workspace | read-write · non-destructive · idempotent · closed-world | | share_create | Create or update a private share draft | read-write · non-destructive · non-idempotent · closed-world | | shares_list | List evidence shares | read-only · non-destructive · idempotent · closed-world | | share_status | Read an evidence share | read-only · non-destructive · idempotent · closed-world | | share_publish | Publish evidence to client viewers | read-write · non-destructive · non-idempotent · open-world | | share_revoke | Revoke client-viewer evidence access | read-write · destructive · idempotent · open-world | | catalog_slice_read | Read a live Shopify catalog slice | read-only · non-destructive · idempotent · open-world | | catalog_slice_snapshot | Mint a catalog slice snapshot | read-write · non-destructive · non-idempotent · open-world | | catalog_slices_saved | Manage saved catalog slices | read-write · destructive · non-idempotent · open-world | | store_claim_by_code | Claim a Shopify dev store by code | read-write · non-destructive · non-idempotent · closed-world | | store_claim | Admin-claim a Shopify dev store | read-write · destructive · non-idempotent · closed-world | | run_start | Start a Shopify dev-store history run | read-write · non-destructive · non-idempotent · open-world | | run_status | Read run status | read-only · non-destructive · idempotent · closed-world | | run_ledger | Read run ledger | read-only · non-destructive · idempotent · closed-world | | run_report | Read run receipt | read-only · non-destructive · idempotent · closed-world | | run_resume | Resume a Shopify dev-store run | read-write · non-destructive · non-idempotent · open-world | | runs_diff | Compare history-run receipts | read-only · non-destructive · idempotent · closed-world | | gate_configure | Configure the Receipt Gate | read-write · non-destructive · idempotent · closed-world | | gate_evaluate | Evaluate the Receipt Gate | read-write · non-destructive · non-idempotent · closed-world | | gate_verdict | Read a Gate verdict | read-only · non-destructive · idempotent · closed-world | | runs_list | List history runs | read-only · non-destructive · idempotent · closed-world | | usage_read | Read usage headroom | read-only · non-destructive · idempotent · closed-world | | twin_diff | Read a twin impact receipt | read-only · non-destructive · idempotent · closed-world | | exam_preflight | Check Shopify Exam readiness | read-only · non-destructive · idempotent · open-world | | exam_start | Start or continue a Shopify Exam | read-write · non-destructive · idempotent · open-world | | exam_status | Read Shopify Exam status | read-only · non-destructive · idempotent · closed-world | | exam_report | Read a Shopify Exam receipt | read-only · non-destructive · idempotent · closed-world | | practice_run_start | Start a practice run | read-write · non-destructive · non-idempotent · closed-world | | practice_runs_list | List practice runs | read-only · non-destructive · idempotent · closed-world | | practice_run_status | Read practice-run status | read-only · non-destructive · idempotent · closed-world | | practice_run_checkpoint | Capture a practice-run checkpoint | read-write · non-destructive · non-idempotent · closed-world | | practice_run_advance | Advance store time | read-write · non-destructive · non-idempotent · closed-world | | practice_run_finish | Finish a practice run | read-write · non-destructive · non-idempotent · closed-world | | practice_run_report | Read a compatibility receipt | read-only · non-destructive · idempotent · closed-world | | practice_run_impact | Read a practice-run impact receipt | read-only · non-destructive · idempotent · closed-world | | get_connection_details | Get practice-store connection details | read-only · non-destructive · idempotent · closed-world | | admin_probe | Run an Admin API probe | read-write · non-destructive · non-idempotent · closed-world | | admin_schema | Look up the Admin API schema | read-only · non-destructive · idempotent · closed-world | | admin_recipes_list | List Admin API recipes | read-only · non-destructive · idempotent · closed-world |

Documentation resources

The same versioned customer documentation is available through standard MCP resources in both the local stdio server and the hosted OAuth resource server:

| Resource | SHA-256 | |---|---| | meguro://docs/gate-policy/v1 | 6d647b3c78fd4e2d93f59a85b90a853096cc73e9cdfd6ba5e3ea505dc07b4aaf | | meguro://docs/gate-policy/v2 | e49378fd745f71aab893db34864aefeb7345c9a25000ad328dfba4e44d007469 | | meguro://docs/gate-policy/v3 | bcd1434cddf99f42261081d9d217285ebf4a93d9e42d23a47bf577c8ee91fbe9 | | meguro://docs/getting-started/v1 | afd19ca6576ae2a8fb03c2e143d25d47fb739682f44180541dd13f779a5f29df | | meguro://docs/getting-started/v2 | 70fdbf36d68a6dd7abb93fe9b403f85c9c0323b3dc3472ab638c6cbe5982ec61 | | meguro://docs/getting-started/v3 | 765cba2b68806f0b1d83255a1742d83ce71ebf7f65f8095e7076cd36e4a1ba6c | | meguro://docs/getting-started/v4 | db534eb544e414be353d6cd4db8dfb9e8dba772dcb10d8287a1a27f8736e5307 | | meguro://docs/getting-started/v5 | 156dcf81266f2bd4e4203dbd09661e49a481395ba4a63528f0540d8ea89bc285 | | meguro://docs/getting-started/v6 | 34cf3ab48a32714b0c3edb24a7920843954172c0d5501e60574adc5a1058071f | | meguro://docs/getting-started/v7 | 650201c983138cb2c34cfef3e93611d510faf42d974f32762207216c3189ece1 | | meguro://docs/index/v1 | 1d52205148a3438339238c9e65271b2c377cd0a96c7088d75de7f2dce9552843 | | meguro://docs/index/v2 | df861c87fa17db23d3173c1d900a884d39b228d493d7e35fcab9b2a531ae9aad | | meguro://docs/index/v3 | 422e91488281867aa2454223a8042248a667c57ea2ae56878bdb136693fe4894 | | meguro://docs/product-guide/v1 | e5450c1b4181cec4d6ed0a498dbff1cb25d2e223ff2228928aecbbce9674f074 | | meguro://docs/product-guide/v2 | b15590df7699f7ad685a30b0698e2c25b5b7b1531afa4e43e9f04a4b38ab9db2 | | meguro://docs/product-guide/v3 | 8dc9e0fae91a2433ea7ca02b9278484250be0d336e2daac96f949da577487dc9 | | meguro://docs/product-guide/v4 | a874a1af1bcf18e7abe6b32b8d226a648b1292458010992528a551c270e9816e | | meguro://docs/receipt-guide/v1 | 9d8150258765d252cb7cc3bad307acdc429b0435ca22f0362b69cf7471e3a333 | | meguro://docs/receipt-guide/v2 | 7df261021b48ce732e6043a8917f8a2673b1f83ff1d8790927abc18f34fb3f6f | | meguro://docs/receipt-guide/v3 | c76b823aed8187834c8ae79a751b53d2720fe7245a31b0b195f440deac9b75cb | | meguro://docs/receipt-guide/v4 | 4a754c5d2de9899ffaafb704e8174617c9c3dc4aa7c4588811a2a0f37faa9133 | | meguro://docs/receipt-guide/v5 | b3b3c83390b1a95ab9e0ec926fb84010070e703cd3a3cef8cecd9fef1c50adfe | | meguro://docs/receipt-guide/v6 | bda3ef240bdf5e6ca075bd00e51253d5d574621cb3feabf11c070aaf7e40ede2 | | meguro://docs/receipt-guide/v7 | 6dba5de1130382c77cccd4be117c002e531863955dea85d4950b36eeb8ecb6fd |

Use resources/list and resources/read when the client supports MCP resources. Use docs_read({ topic, version }) in every client, including clients without a resource browser. Published versions are immutable and carry a SHA-256 digest; later versions are appended under a new URI instead of replacing an existing document.

Identity model

Hosted OAuth grants are issued only to an active account owner and are account-bound, not pinned to one workspace. Account-scoped tools such as workspaces_list and workspace_create need no selector. Store-fleet, share, catalog-slice, and claim tools accept an optional workspaceId: omit it for the default workspace, or pass an exact id from workspaces_list for a non-default workspace. The hosted resource server verifies that selection against the token account before dispatch.

Local meg_sk_… API keys remain workspace-bound. A key may omit workspaceId or repeat its own binding, but cannot switch workspaces; use a key issued from the intended workspace instead. Tier capacity and workspace ownership are always server-derived. Workspace-bound keys may list account workspaces through the existing read route, but account-level create/archive/unarchive requires the owner-only OAuth lane.

The whole assistant workflow uses exactly two identifiers:

• storeId — the canonical public practice-store id. get_connection_details takes it and returns it, and practice_run_start consumes it verbatim, so connection-discovery output passes directly into run start. worldId is a legacy alias for the same id (both tools still accept it and connection results still include it); prefer storeId in new integrations.
• attemptId — the run identity returned by practice_run_start. Every later practice_run_* tool takes attemptId, never the store id.

Receipt retrieval is practice_run_report: receipt is the user-facing noun; report (the tool suffix, the /report route, and the operation: "report" result field) is the protocol/route implementation compatibility name for the same artifact.

External-agent practice sequence

Use these tool names in order:

1. templates_list() to discover the supported template keys.
2. stores_list(), then reuse an owned store or call store_create({ templateKey }).
3. get_connection_details({ storeId }) through the explicit secure flow (worldId remains a legacy alias). Follow its structured adminExecutionGuide; keep returned credential values out of model/chat logs.
4. practice_run_start({ storeId, clock: { mode: "harness", simulationDays: 14, stepDays: 1 } }) — the same storeId the previous step took and returned.
5. Launch the agency agent in its own environment with the stable returned SHOPIFY_* values.
6. practice_run_status({ attemptId }), then practice_run_checkpoint({ attemptId }).
7. practice_run_advance({ attemptId, days: 1, expectedDay, expectedCallSeq }), using the exact current state cursors. Supply until instead of days for a supported event stop.
8. Inspect the aligned checkpoint evidence in Console or the run APIs.
9. practice_run_finish({ attemptId }), then practice_run_report({ attemptId }) for the run's receipt.

get_connection_details deliberately returns SHOPIFY_ADMIN_ACCESS_TOKEN: it is the store-scoped data-plane credential your commerce agent needs for the exact returned *.meguro.io Admin URL. Treat it as a secret, provide it only to that agent process, and keep it out of model/chat logs. It is not the account-scoped MEGURO_API_TOKEN and cannot control other stores or account resources.

Hosted OAuth and the public package's MEGURO_API_TOKEN authenticate MCP/control-plane calls only. Admin GraphQL calls use the returned Admin URL and the per-store token in X-Shopify-Access-Token; never send the OAuth bearer to the Admin URL. Before one bounded write, read admin_schema's match.executionRequirements for the required run state, any exact preflight read, valid next calls, and the authority-derived idempotency example.

manual, harness, and scheduled are clock ownership modes. Raw Admin GraphQL requests do not each advance time. Practice-run status, checkpoint, and receipt responses deliberately exclude raw private evidence and credentials; get_connection_details is the one explicit credential-returning tool.

Generate the exact placeholder-only MCP sequence from the repo:

node byo-ci-test/phase7-snippets.mjs mcp

See the agency quickstart and HTTP reference.

Advanced: CI or local STDIO

Use the public STDIO package for CI, local automation, or clients without hosted Streamable HTTP and OAuth support. It requires a workspace-bound meg_sk_… API key and exposes the full 47-tool local surface. Pin the exact public version in client configuration so a quickstart stays reproducible:

npx -y [email protected]

Environment

MEGURO_API_BASE_URL=https://api-dev.meguro.io
MEGURO_API_TOKEN=<meg_sk account key from Console → Settings>
MEGURO_DASHBOARD_URL=https://<dashboard-distribution>.cloudfront.net   # optional, enables dashboard links

Register — Claude Code

claude mcp add meguro \
  -e MEGURO_API_BASE_URL=https://api-dev.meguro.io \
  -e MEGURO_API_TOKEN=meg_sk_... \
  -e MEGURO_DASHBOARD_URL=https://... \
  -- npx -y [email protected]

Register — Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "meguro": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "MEGURO_API_BASE_URL": "https://api-dev.meguro.io",
        "MEGURO_API_TOKEN": "meg_sk_...",
        "MEGURO_DASHBOARD_URL": "https://..."
      }
    }
  }
}

Then, in your assistant: "Start a Meguro world with 12 months of history on <SHOP_DOMAIN>, seed bfcm-regression, and give me the dashboard link."

Tests

npm test --workspace meguro-mcp

The test suite packs the public artifact, installs it into a temporary clean-room project, starts the installed binary, and requires tools/list to return exactly 48 tools without leaking supplied credentials to stdout or stderr. Maintainers should follow RELEASING.md for every version; release notes are in CHANGELOG.md.