Help CenterSettings / Team / Member

How do I let AI query my store data?

Page Settings / Team / MemberUpdated 2026-11-21
Short answer

Create a role with only View permissions in Roles; then create a sub-account in Sub-accounts, choose Virtual AI staff as the type and assign that role; in that sub-account's actions click APP KEY to generate an APP ID / APP KEY pair, and copy the client configuration from the dialog into your AI client. The AI can then query the data within its permissions.

MCP is the common way for AI clients to connect to outside systems. Once connected, you can ask your AI things like "Which store had the most refunds last week?" or "How much stock is left for these SKUs?" and it will run the system's queries and summarize the results for you. Everything is read-only; no data is changed.

Step 1: Create a read-only role

Go to Settings → Team → Roles and create a role, for example "AI query". Tick only the View permission of the pages the AI should see.

  • The role decides what the AI staff can query: pages that are not ticked do not appear in its tool list and cannot be called.
  • Amount, cost and profit fields follow the role's field permissions, the same as for human sub-accounts.
  • Even if edit or delete permissions are ticked, AI staff can only query.

Step 2: Create a virtual AI staff member

Go to Settings → Team → Sub-accounts and click New sub-account:

  1. Choose Virtual AI staff as the account type. It cannot sign in to the website, so no email or password is needed.
  2. Enter a user name (for example "AI assistant") and choose the role from step 1.
  3. Limit store, warehouse and product permissions as needed. The AI can only see the stores, warehouses and product categories granted here.
  4. Click Save.

The account type cannot be changed afterwards. In the list, its account column shows Virtual AI staff.

Step 3: Generate an APP KEY

In that row's actions, click the key icon APP KEY, then Generate APP KEY. The dialog shows:

  • MCP address: the address the AI client connects to.
  • APP ID / APP KEY: a pair of credentials, like the AI staff member's account and password.
  • Client configuration: a ready-made snippet with the three values above. Click Copy.

The APP KEY is shown only once. After the dialog closes nobody can see it again, so copy it right away. The list below records each pair's creation time, last use and status.

Step 4: Add it to your AI client

In your AI client's MCP server settings, add a server and paste the configuration from step 3. It looks roughly like this (use the one copied from the dialog):

{"mcpServers": {"merchantos": {"type": "streamable-http","url": "https://your-system-domain/api/mcp","headers": {"app-id": "your APP ID","app-key": "your APP KEY"}}}}

Some clients ask for the fields separately: choose Streamable HTTP (sometimes shown as http) as the type, enter the MCP address, and add two request headers app-id and app-key.

Once connected, the client lists a set of query tools named after the system's interfaces (orders, inventory, reports and so on). Each tool's description says which page it belongs to and which permission it needs.

Are the results the same as on the website?

Yes. Every AI query goes through the same query as the website, with the same permissions, store scope and field masking. The only difference is that AI staff never see buyer contact details.

  • Most list queries support paging. A very large result (over 200,000 characters) is cut off, and the AI will add filters or page through as prompted.
  • Querying too often returns a "try again later" message, the same limit as the website.

How do I know what the AI looked at?

Every connection, tool-list read and query is recorded in Settings → Operation log, with the AI staff member as the operator, the page it queried and the APP ID it used.

Stop the AI from querying

  • Rotate the APP KEY: generate a new pair, switch the client to it, then revoke the old one. There is no downtime.
  • Pause: turn its status off in the sub-account list. Disabling also revokes all its APP KEYs; generate new ones after re-enabling.
  • Remove for good: delete the sub-account.

Cannot connect or nothing comes back

What you seeWhyWhat to do
Unauthorized when connectingWrong APP ID or APP KEY, the key was revoked, or the AI staff member is disabledCheck the configuration; generate a new pair if it was revoked or disabled
The tool list is emptyIts role has no View permission on any pageTick the pages in Roles
No permission for this toolThe role does not include that pageTick that page's View permission for the role
Amounts or costs are emptyThe role's field permissions are not tickedTick them in field permissions as needed
Too many queriesToo many queries in a short timeWait a minute and try again

Who can manage this

  • Viewing AI staff and their APP KEY list needs the View permission of Sub-accounts; creating AI staff, generating and revoking APP KEYs and disabling need the Edit permission of Sub-accounts.
  • A sub-account can only manage colleagues within its own scope and cannot give AI staff more permissions or stores than it has itself.