15 tools, 9 scopes: what an assistant can ask your store

| Scope | What the assistant can ask for | Tools | Shopify grant needed | |---|---|---|---| | boostecom:store.read | the store's identity, context and API schema | getShopInfo, getStoreContext, introspectSchema | none | | boostecom:catalog.read | products | listProducts, getProduct | read_products or write_products | | boostecom:orders.read | orders | listOrders | read_orders or write_orders | | boostecom:content.read | pages | listPages | read_content or write_content | | boostecom:themes.read | themes, plus a theme audit | listThemes, getTheme, runAudit | read_themes, write_themes or write_theme_code | | boostecom:analytics.read | ShopifyQL queries | runShopifyQL | read_analytics or read_reports | | boostecom:graphql.read | an open Admin GraphQL passthrough | shopifyAdminGraphQL | none, Shopify decides per query | | boostecom:studio.read | a Studio section | getStudioSection | none, the person's own Studio permission is what counts | | boostecom:docs.read | the public documentation | searchDocs, getDoc | none |

Any one of the listed grants opens a row.

The server actually registers seventeen tools. The last two read the team's internal documentation: they are reserved to BoostEcom administrators, withheld from a customer's consent screen, and the role is re-read from the database on every call. They are not counted here, because no customer can obtain them.

A tool is registered for a session only if it clears three gates:

1. The consented scope. What the person approved for this client.
2. The store's Shopify scopes. A hard ceiling: if the custom app was never granted read_orders, no BoostEcom consent makes listOrders appear.
3. An identified caller, only for tools whose permission hangs off an organization membership. With a static key there is nobody to check, so those tools are not offered.

A tool that fails a gate is not registered. It is missing from the list, rather than listed and failing on call.

I picked that behaviour for a plain reason: an AI client tries the tools it can see. A visible but forbidden tool burns conversation turns, and often produces a confident, wrong explanation of why it failed. Hiding the tool turns the list itself into the permission document.

The cost: two connections to the same store can show two different lists, depending on what each one consented to and how it authenticated. That is the gate working, not a bug.

A scope's family decides who can exercise it:

• relay goes through the bridge to Shopify. A static key is enough, because the key is bound to one store and holding it is the authorization.
• native reaches a BoostEcom system (today, Studio). It requires an identified caller, so a static key never opens it.
• public reaches what a stranger can already read without an account. Its scope protects nothing. It lets a client decline those two tools to keep its list short, and it puts them on the consent screen.

Every scope ends in .read, and that is more than a naming habit.

The tricky one is shopifyAdminGraphQL, which accepts any GraphQL document. The relay classifies each document before sending it:

• a query goes through;
• a mutation classified as critical (publishing or deleting a theme, deleting a product, customer or order, refunding, uninstalling an app) is refused;
• every other mutation, and any document the classifier cannot read, is refused as well.

The refusal happens before the request reaches Shopify, and every write attempt is journaled, refused or not. BoostEcom does have writes, just somewhere else: the dashboard chat, behind human approval.

• It writes nothing. No price edits, no product creation from a chat. That is a different tool's job.
• It does not read the market. Intelligence data about other stores does not flow through this relay today: no scope on the list exposes it.
• It never goes past Shopify. The catalogue is a maximum. What a given store exposes depends on its custom app.

The reference version, kept in sync with the code, is the MCP tools and scopes page.

• Sources: the scope catalogue in the code, the file that registers tools on the server, the GraphQL risk classifier, and the public MCP server and tools and scopes pages.
• Automation: an AI assistant drafted the first pass. The fifteen tools, the nine scopes and the two reserved tools were recounted in the code.
• A correction along the way: our internal notes said eleven scopes. The code declares ten, one of them reserved to the team; eleven only held if you counted the old single mcp scope. This post uses the code's number.
• What I added: the review and the call to publish.

Verified on September 13, 2026.