How do I let AI query my store data?
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:
- Choose Virtual AI staff as the account type. It cannot sign in to the website, so no email or password is needed.
- Enter a user name (for example "AI assistant") and choose the role from step 1.
- Limit store, warehouse and product permissions as needed. The AI can only see the stores, warehouses and product categories granted here.
- 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 see | Why | What to do |
|---|---|---|
| Unauthorized when connecting | Wrong APP ID or APP KEY, the key was revoked, or the AI staff member is disabled | Check the configuration; generate a new pair if it was revoked or disabled |
| The tool list is empty | Its role has no View permission on any page | Tick the pages in Roles |
| No permission for this tool | The role does not include that page | Tick that page's View permission for the role |
| Amounts or costs are empty | The role's field permissions are not ticked | Tick them in field permissions as needed |
| Too many queries | Too many queries in a short time | Wait 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.