MCP server
Connect an AI agent to the reviews of your own store — read them, approve them and reply to them from the assistant you already use.
What is the MCP server?
MCP (Model Context Protocol) is an open standard that lets an AI agent call tools on an external service. The Air Reviews MCP server exposes the product reviews of your store, and only your store, so an agent such as Claude Desktop can answer questions about them and act on them for you.
The server is read-only except for two write tools. Those two can approve or unapprove a review and add the store owner's public reply — nothing else. An agent connected here cannot change your settings, cannot read your orders or customers, and cannot create or read MCP credentials.
Your credential is checked on every single call and never cached. Revoking one — or uninstalling the app — stops it working on the very next call, with no grace period.
How to set it up
Create a credential
In the Air Reviews admin, go to Settings → Integration → MCP server, then click Create credential. Give it a label that says which client will use it, and pick the scopes that client actually needs.
Copy the credential
The value appears once, in a banner at the top of the page. Copy it into your MCP client or a password manager before you close that banner.
The credential is shown exactly once. It is stored only as a hash, so neither you nor Avada support can display it again later. If you lose it, that is not a disaster — just create a new credential and revoke the old one.
The value looks like this:
arv_mcp_<keyId>.<secret>Both halves matter: the part before the dot identifies the key, the part after it is the secret. Pass the whole string, dot included, exactly as shown.
Point your MCP client at the server
| Endpoint | https://app.airreviews.io/mcp |
| Authentication | Authorization: Bearer arv_mcp_<keyId>.<secret> |
For a client that reads a JSON config file (Claude Desktop and similar), add an entry like this:
{
"mcpServers": {
"air-reviews": {
"url": "https://app.airreviews.io/mcp",
"headers": {
"Authorization": "Bearer arv_mcp_<keyId>.<secret>"
}
}
}
}The credential must travel in the Authorization header. Never put it in the query string — URLs end up in browser history, proxy logs and server access logs, and a credential that reaches a log file has to be treated as leaked.
Checking it yourself
Before wiring up a client, you can confirm the credential works with one command. It asks the server which tools it offers:
curl -sS https://app.airreviews.io/mcp \
-H "Authorization: Bearer arv_mcp_<keyId>.<secret>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'A successful response lists the tools below. What the different failures mean:
| Status | Meaning |
|---|---|
401 | The credential is wrong, expired or revoked. |
403 | The credential is valid, but access is refused — the store is disabled, or the app has been uninstalled from it. The response body says which. |
429 | You have hit a rate limit. See Rate limits. |
The four tools
The table below summarises what each tool does. The server hands your agent a longer, more precise version of each description — the wording differs slightly, but the behaviour described here is the behaviour you get.
| Tool | What it does |
|---|---|
list_reviewsread | List product reviews for this store, newest first by default. Use it to answer "what is waiting for me", "what are the recent 1-star reviews", or to find the reviewId needed by the write tools. Customer email and phone are never returned. |
set_review_statuswrite | Approve or unapprove ONE review, by id. approved publishes the review on the storefront; disapproved hides it. Both directions are reversible by calling the tool again. Deleting is not possible here. |
reply_to_reviewwrite | Write the store owner's public reply to ONE review, by id. By default the reply is saved to the review only and no email is sent, so you can read it in the admin before anything leaves the store. A review is emailed at most once: reply a second time and the new text is saved, but no second email goes out — the answer tells you so rather than pretending it sent one. |
get_review_settingsread | Read this store's review configuration: moderation rules, the review block, the submit form, and all six storefront widgets — star rating, sidebar, carousel, review popup, testimonials and customer-portal reviews. Takes no arguments and changes nothing. Use it to explain why the store behaves as it does — why a new review is not live yet, who is allowed to write one, whether a widget is switched on. It returns a fixed set of fields only: for each widget its on/off switch and the rules deciding when it shows, but no email or SMTP configuration and no colours, fonts, CSS, positions or timings. |
Two behaviours are worth repeating, because they are the ones that surprise people.
reply_to_review sends no email unless you explicitly ask for one by setting notifyCustomer. Once an email has gone out, no tool can take it back.
Review text written by shoppers is returned to the agent under an untrusted key. That is deliberate: it signals that a review's contents are data to be summarised or quoted, never instructions to follow.
Scopes
Each credential carries scopes that decide which tools it may call.
| Scope | Grants |
|---|---|
reviews:read | Read reviews. |
reviews:write | Change review status and write replies. |
settings:read | Read the review configuration. Never includes email or SMTP settings. |
A credential created without an explicit choice gets reviews:read only. That is the safe default: give a credential write scopes only when the agent using it actually needs to change something.
Rate limits
Every store gets the same allowance: 4 requests per second. There is no monthly cap, and no plan changes this number.
Reads and writes come out of that same allowance, and a write costs two of it. So within one second you can make four reads, or two writes, or one write and two reads.
Going over returns 429 with a Retry-After: 1 header. The next second starts clean, so an agent that waits a moment and retries will get through.
Managing your credentials
The admin page lists each credential by label, scopes, the last four characters of the secret, and its creation, expiry and last-used dates — enough to tell them apart without ever revealing them.
- You can hold up to 10 active credentials at a time. If you reach that limit, revoke one you no longer use before creating another. Revoked and expired credentials do not count towards it.
- A credential is valid for 365 days from the moment you create it. Create a replacement before the expiry date shown in the admin, then revoke the old one.
- Revoking takes effect on the next MCP call. The record itself is kept, marked as revoked, so past activity stays traceable.
- Uninstalling the app revokes every credential, permanently. Reinstalling does not bring them back — you create new ones and point your MCP client at them. This is deliberate: an app you have removed should not keep reading and writing your reviews.
- The Last used column refreshes at most once every five minutes, to keep the server fast. A credential in active use right now may show a timestamp several minutes old — that is normal, not a sign it has stopped working.
Keeping your credential safe
A credential grants everything its scopes allow, on your store, to whoever holds it. Treat it like a password, not like an ID.
- Never commit it to a Git repository, paste it into a shared document, or send it over chat.
- There is no way to view it again after creation — plan for that instead of working around it.
- Give each client its own credential with its own label. Then if one has to be revoked, the others keep working.
- If you suspect a credential has leaked, revoke it in the admin and create a new one. It costs you a minute and closes the hole on the next call.