Permissions and safety

A DataGlass MCP connector starts read-only and stays read-only until you approve a write scope, and each scope unlocks one domain only. Since 3 August 2026 the connector is write-capable: an assistant that holds the right scope can apply a price-tier draft, change an ad group's budget, write COGS, cancel an order, or ship a package. Nothing is granted by default, every scope is approved by you on the consent screen, and every tool that reaches a marketplace announces itself as destructive so your assistant asks before it runs.

The DataGlass MCP permission model in four layers

1. Default deny. A newly issued connector carries only the read baseline. It can report, compare, diagnose, recommend, and simulate. It cannot change anything.
2. Per-domain write scopes. Write ability arrives only through an OAuth scope you approve, and each scope covers one domain. A seller can let an agent manage ad spend without letting it touch prices.
3. Destructive-tool confirmation. Every mutating tool advertises readOnlyHint=false and destructiveHint=true, which is what makes Claude and ChatGPT prompt before executing. The tool's own description spells out what changes and, where one exists, names the preview or read-back tool to run first.
4. Mediated writes only. Write tools go through DataGlass's own pricing, ads, catalog, and fulfilment flows — the ones that compute the resulting margin and record a rollback state. Raw marketplace passthroughs are not exposed as tools at all.

The nine per-domain write scopes

Return and refund decisions sit behind their own scope rather than riding along with orders or logistics, because they move real money and the platform will not reverse them.

Granting a write scope never widens your DataGlass role. The PAT_* scopes unlock the agent write gate only; organization permissions, shop-ownership guards, and the sensitive-financial rules all still run on every call exactly as they do in the app.

Mediated writes versus raw marketplace passthroughs

The connector writes through DataGlass, never straight through to a marketplace API. This is the architectural line that decides which capabilities exist as tools at all.

A mediated path — a price-tier draft, a target-margin apply, a recommendation apply — computes the resulting margin before it acts, records a draft or rollback state, and converges with the rest of the pricing product, so the number you see in DataGlass and the number the buyer sees agree afterwards. These are the paths exposed as tools.

A raw passthrough — updatePrice, addDiscount, updateStock, and the voucher, bundle-deal, flexi-combo, and free-shipping partner calls — pushes a value at the marketplace and returns. DataGlass would then hold one price and the marketplace another. Those handlers exist for the app's own use but are deliberately not agent-reachable.

The honest consequence: vouchers, bundle deals, flexi-combo, and free-shipping campaigns have no mediated equivalent, so those capabilities are simply absent from the agent surface. An assistant cannot create or edit them for you at any scope. Do them in the app or in Seller Center.

Tools that create live marketplace listings

Two catalog tools call the platforms' own create-product APIs and produce listings buyers can see:

• create_canonical_product creates a new live listing on every selected Shopee, Lazada, and TikTok shop, then binds them to one shared canonical product.
• copy_product_to_shops re-creates an existing listing as a new live listing on each target shop, including a different platform.

Both are labelled destructive for that reason. Neither is a canonical-row-only operation. Read the full payload back — shops, title, price, stock — before you approve one.

Two profitability lists withheld from the agent surface

The Shopee price-tier review queue and the campaigns-losing-by-profit-adjusted-ROAS list were deliberately withdrawn from the tool surface on 3 August 2026. Membership in either result set is the financial signal: being in the queue means margin sits below the floor, and being in the losing list means true profit is negative. Shading the values would still leak that to a team member without VIEW_SENSITIVE_FINANCIAL, and a tool would make it enumerable across every shop in one call.

Both still work inside the DataGlass app and over the REST API, under the usual page permissions. Only the agent surface is narrower.

API keys from the app are read-only; OAuth connectors carry the scopes you approve

There are two ways to hand DataGlass credentials to an agent, and they differ:

So a dg_pat_ token you pasted into a script cannot write, even though the connector you approved in Claude might. When someone reports that "the API is read-only," this is usually the distinction they mean.

The Pro plan requirement for MCP and API keys

Both MCP tool calls and Personal Access Token creation require PlanTier.PRO. A caller below Pro receives a plan-denied response rather than a tool result. Do not describe API or MCP access as included in every plan.

Rate limits and the fail-closed rule for write-capable keys

Each key is throttled at 60 requests burst, 1 request per second sustained, keyed per key so one runaway agent cannot starve your dashboard. An MCP tool's internal fan-out does not consume extra tokens; the outer /mcp call already spent one.

When the limiter itself is unavailable, the behaviour splits by capability. A read-only key fails open — the token was already validated, and an outage should not take reads down. A write-capable key fails closed, because an unthrottled agent looping over a mutating tool changes live prices and ad spend, which is not a cost worth paying to keep reads up.

Tenant isolation across the API-key surface

A full trace of every API-key-reachable endpoint — 625 handlers — found no cross-tenant read and no cross-tenant write. Every tool call is dispatched as an authenticated request carrying your own token, so ownership guards run exactly as they do for a request from the app.

Sensitive financial shading survives the agent boundary

A value hidden by VIEW_SENSITIVE_FINANCIAL arrives at the assistant as the string "***" — or null for an object or list — not as a real number. Render it as a locked field. Do not coerce it to zero, do not treat it as missing data, and do not retry around the permission. Where ordering itself would disclose a shaded value, the sort is stripped too.

Production endpoints

Product-search results can contain relative links such as /products?canonicalId=123. Resolve them against https://app.dataglasslabs.com, never against the API origin.

There is no public OpenAPI spec. An agent spec is generated internally at /v3/api-docs/agent from the live access rules, but it is IP-allowlisted and returns 404 to the public internet. Runtime tools/list is the machine-readable contract for a connected assistant.

Business terms used in answers

Do not promise live marketplace data or guaranteed future results.

Assistant workflow for a DataGlass question

1. Discover the selected shop using the matching list_*_shops tool. Never invent shopId, sellerId, or region.
2. For "how is my shop?" or "what changed?", begin with diagnose_shop.
3. Read signals[] and follow a signal's suggestedTool only when the question needs that evidence.
4. Compare like-for-like periods and state the window and local currency.
5. Lead with the largest business driver, then show up to three supporting facts and a next step.
6. State when COGS is inferred, recent settlement is incomplete, a field is permission-shaded, or the result is simulated.
7. Before any write, name the tool, the exact objects it will touch, and the current-versus-proposed values — then wait for an explicit go-ahead.
8. After a write, say what actually changed and name the rollback or revert tool if one exists.

Language for read results versus writes

Use "preview," "simulate," "recommend," or "review in DataGlass" for anything the assistant has only read or modelled. Say "applied," "updated," "cancelled," or "shipped" only after a write tool returned successfully — and name the tool that did it. Claiming a change that did not happen, and failing to report one that did, are equally serious errors.

Note that "rollback" rarely means undo. A price rollback issues a fresh set of platform writes to restore the captured pre-apply prices; buyers see prices change again. Some actions — a cancelled Shopee order, an accepted TikTok return — cannot be reversed at all.

Identifiers

• Get shop IDs and regions from list_shopee_shops, list_lazada_shops, or list_tiktok_shops.
• Use canonical product IDs only after search, list_products, or another product result returns them.
• Do not infer a marketplace from the shape of an ID.
• TikTok shop, campaign, advertiser, product, and SKU IDs can exceed JavaScript's safe integer range. Preserve them as opaque strings from browser to MCP and back.

diagnose_shop currently derives its schema from a Kotlin Long path value. Pass a TikTok shop ID exactly as returned by list_tiktok_shops. If a strict host cannot preserve it without numeric coercion, use the TikTok-specific financial overview tools.

Dates and comparisons

Payout tools filter by payout or settlement date, not order date. Recent realized values can be incomplete while marketplace settlement is pending; show a settlement-lag note instead of treating the latest decline as final.

Money, VAT, and COGS

• Money uses the shop's local currency. Do not sum unlike currencies without explaining the rollup.
• includeVat=false is the normal forward-VAT view unless the user asks otherwise.
• includeInferredCogs=true fills missing COGS with DataGlass's estimate.
• Label ranked loss-makers and simulations that depend on inferred costs.
• Writing COGS changes every profit and margin number for the affected products, historical reports included. Preview it first.

Pagination and call cost

• Begin with counts, diagnostics, or top and bottom summaries when they answer the question.
• Use search before a broad catalog list when the user gives a product name, SKU, model SKU, or listing ID.
• For cursor results, pass the response's nextCursor values into the next call.
• Fetch more pages only for exhaustive output or when the decision truly requires it.

OAuth consent contract

The MCP host starts OAuth at the API domain. After validation, DataGlass redirects the browser to https://app.dataglasslabs.com/connect with client_id, optional client_name, redirect_uri, scope, optional state, code_challenge, code_challenge_method=S256, and optional resource.

The consent page must:

1. Preserve every query parameter across sign-in and return the user to the exact consent URL.
2. Show the read baseline plus every requested PAT_* write scope, named in plain language, so the user can see which domains the client will be able to change.
3. Display the validated client_name when present without implying DataGlass owns the client.
4. Require an explicit allow or deny decision.
5. POST snake-case fields to https://prod-api.dataglasslabs.com/api/oauth/consent.
6. Send the DataGlass JWT in Authorization: Bearer ...; the endpoint intentionally ignores the ambient access-token cookie to prevent consent CSRF.
7. Use approve: true for allow and approve: false for deny.
8. Navigate only to data.redirectTo returned by the backend.
9. Clear pending consent state after navigation or cancellation.

{
  "client_id": "...",
  "redirect_uri": "...",
  "scope": "...",
  "state": "...",
  "code_challenge": "...",
  "code_challenge_method": "S256",
  "resource": "...",
  "approve": true
}

Consent copy should state both halves — what the client reads, and what it may change:

Connect DataGlass to {clientName}? {clientName} will be able to read analytics for the shops available to your DataGlass account, including products, orders, profit, ads, recommendations, and inventory. If you also approve the write permissions listed above, it will be able to change those things in your shops.

When no write scope is requested, say so plainly and label the button Allow read-only access. When one or more is requested, the button must not claim read-only access.

Response design

A useful answer follows this order:

1. Scope: shop and platform, date range, comparison, and currency.
2. Headline: the most important conclusion in one sentence.
3. Evidence: no more than three key metrics or ranked drivers initially.
4. Confidence: COGS coverage, settlement lag, permissions, or simulation assumptions.
5. Next step: a follow-up question, another simulation, a proposed write, or a DataGlass deep link.

Error recovery

Prompt and connector analytics

Track stable prompt-pack identifiers instead of raw prompt text. Useful events include:

• mcp_prompt_impression and mcp_prompt_selected with prompt_pack, scenario, surface, and optional platform;
• mcp_connector_started, mcp_connector_allowed, mcp_connector_denied, and mcp_connector_failed;
• mcp_answer_followup_selected with a follow-up type;
• mcp_deep_link_opened with a route category, never raw financial content.

Never log OAuth codes, PKCE values, access or refresh tokens, buyer information, raw prompts containing order details, or tool responses.

Adding a prompt to the library

1. Choose one business outcome and the matching prompt pack.
2. Confirm the required capability exists in the tool catalog and runtime tools/list.
3. Write at least three scenarios: broad assessment, focused investigation, and decision or next action. Add a comparison or data-quality case when distinct.
4. State which scope the prompt needs. If it can be answered read-only, say so; if it ends in a write, name the tool and the scope.
5. Verify every ID in the prompt can be discovered rather than guessed.
6. Define empty, permission-shaded, plan-denied, missing-scope, and incomplete-data behavior.
7. Test every platform claimed by the prompt.
8. Keep product links on https://app.dataglasslabs.com.