MCP Server
Last updated: November 17, 2026
BetterReviews is an MCP server (Model Context Protocol, Streamable HTTP transport, protocol version 2025-06-18). Instead of writing curl calls, an AI client gets a small set of tools over your store: search the review corpus, list reviews in any state (including the pending Inbox), read a review, approve, reject and reply to reviews, read review stats and your plan and AI credit usage, pull the best reviews for a product, record and manage marketing claims, link supporting reviews, ask a reviewer for permission to feature their review, read, generate, edit, save and export your Studio ads and emails, and run the whole product-page optimization loop — regenerate, edit, fact-check, approve and publish.
The server is stateless and plain JSON: every POST carries one JSON-RPC 2.0 message and gets one JSON response; a notification gets 202 with no body. There are no sessions, no server-sent events and no batching.
Two ways to connect
| Door | URL | Auth | Tools |
|---|---|---|---|
| Header | https://api.betterreviews.app/api/v1/mcp | X-API-Key header with a store API key | All thirty (nineteen need Read & Write) |
| Connector URL | https://api.betterreviews.app/api/v1/mcp/c/<token> | The URL itself (a connector token, up to 90 days) | Read-only eleven |
Claude Code
claude mcp add --transport http betterreviews https://api.betterreviews.app/api/v1/mcp \
--header "X-API-Key: YOUR_API_KEY" Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"betterreviews": {
"type": "http",
"url": "https://api.betterreviews.app/api/v1/mcp",
"headers": { "X-API-Key": "YOUR_API_KEY" }
}
}
} claude.ai and ChatGPT custom connectors
claude.ai and ChatGPT connectors cannot send headers, so you use a connector URL instead. There is no button for this in the BetterReviews app yet, so you make the URL with one API call:
- In the BetterReviews app, go to Settings → Integrations → API access → Create token, choose Read & Write, and copy the key. Minting a connector URL needs a Read & Write key; the URL itself is read-only.
- In a terminal, run the request below with that key. The
201response carriesurl, shown once, so copy it straight away. - Paste
urlas the connector URL in claude.ai, or add it as a custom connector in ChatGPT. - Optional: if you created the Read & Write key only for this, revoke it under Settings → Integrations → API access. The connector URL keeps working until it expires (90 days) or is revoked, unless the key had an expiry date, in which case the URL expires with it.
curl -X POST https://api.betterreviews.app/api/v1/mcp/connector-tokens \
-H "X-API-Key: YOUR_API_KEY" {
"id": "…",
"name": "mcp-connector",
"prefix": "ppo_AbCd",
"expires_at": "2026-12-12T10:00:00Z",
"url": "https://api.betterreviews.app/api/v1/mcp/c/ppo_…"
} About the connector URL:
- Treat the URL as a password. Anyone who has it can read your reviews, claims and saved creatives until it expires or you revoke it.
- It is read-only: only
search_reviews,list_reviews,get_review,review_stats,get_usage,top_reviews,list_claims,permission_preview,get_optimization,list_creativesandget_creativeare available. Mutating tools are not listed and returnread_only_tokenif called. - It expires after 90 days (or when the key that minted it expires, if sooner); at most two are active per store (
422 too_many_connector_tokens). - It only works at its own URL. Presented as a header, Bearer token or query parameter anywhere on the REST API it is refused with
401. - Revoke it from Settings → Integrations → API access in the BetterReviews app (it appears as
mcp-connector) or withDELETE /api/v1/mcp/connector-tokens/:id. Revocation is immediate.
Managing connector tokens requires a Read & Write API key: POST mints, GET /api/v1/mcp/connector-tokens lists the active ones as {"data": [...]} (id, prefix, last used, expiry — never the URL), DELETE /:id revokes.
Tools
| Tool | Auth | Arguments | Returns |
|---|---|---|---|
search_reviews | either | query (required, ≤500 chars), product_id, min_rating 1–5, limit 1–50 | reviews[], total, has_more. Natural-language search over the corpus. Requires an active paid subscription (Good, Better, Studio or a legacy paid plan) — the Free plan gets subscription_required. |
get_review | either | review_id | Rating, title, content, display name, status, stage, rights_status, tags, media count. Never the reviewer's email. |
list_reviews | either | status (pending | approved | rejected), stage (needs_review is the Inbox; also analyzing, needs_support_email, awaiting_support, on_hold, indefinite_hold, awaiting_team, published, archived, rejected), min_rating / max_rating 1–5, product_id, review_kind (product | store), date_from / date_to (ISO 8601 date or datetime on the review date; a bare date means 00:00 UTC), limit 1–50 (default 20), offset 0–10,000 | {reviews[], total, limit, offset, has_more}, newest first. Reviews in any state, including the pending queue that search_reviews and top_reviews do not return. When both status and stage are given, stage wins. Each row has the get_review shape plus reply: the store's existing public reply as {body, updated_at}, or null. Never the reviewer's email (unlike REST GET /reviews). invalid_product_id, invalid_date or invalid_date_range for a bad filter. |
review_stats | either | keyword_limit 1–50 (default 20) | The GET /reviews/stats body (counts by status, stage, rating and platform, average rating, recent volume, keyword totals) plus sentiments[] (from GET /reviews/sentiments, published reviews only) and top_keywords[] ({name, tag_group, review_count}, as GET /reviews/keywords). Aggregates only, no review text. |
get_usage | either | none | {plan, subscription_status, entitlements, usage}, the same summary the BetterReviews app reads. usage has exactly these fields: used, limit, remaining (AI credits this period; the lifetime playground pool on Free), usage_kind (credits | playground), plan, period_start, spent_this_period_cents, upgrade_nudge, peek, resolved_tier, active_subscription_cap_cents, auto_recharge_enabled, auto_recharge_state, cap_reached and block_unavailable. entitlements maps each plan feature to true/false, plus ai_conversations ({metered, used, remaining, usage_kind}). Read-only: it never changes billing. |
top_reviews | either | product_id (required, ≤64 chars), objective (marketing | helpful, default marketing), limit 1–20 (default 3), min_rating 1–5, exclude_ids (≤50 review IDs) | {reviews[], tier, coverage, objective}. The best reviews for one product, ranked in SQL — no model call, no AI cost. Each row carries id, product_id, rating, title, content, reviewer_display_name, is_verified_buyer, rights_status, word_count, quality_score, review_created_at and media_count — the same key names as get_review, not the REST endpoint's created_at/media[] shape. There is no require_media argument (REST only), and limit defaults to 3 here versus 5 on REST. tier is A (some reviews AI-analyzed) or C (none yet, analysis-free ranking); coverage is {total, analyzed}. Product-scoped: Review Group siblings are never pooled in. Capped at 60 calls/minute per store on top of the shared limit, in a bucket shared with GET /reviews/top. |
list_claims | either | product_id, status, collect_enabled, include_archived, limit, offset | Same shape as GET /claims. |
permission_preview | either | review_id | {reachable, masked_email} — the full address never leaves the server. |
upsert_claim | header + write | Create: product_id, claim_text, topic, source (+ optional ask_phrasings, status, collect_enabled). Update: claim_id + fields. | {claim}. Same validation as the REST API (invalid_prompt_text, product_not_found, another_claim_active). |
set_claim_collection | header + write | claim_id, enabled | {claim}. One collect-enabled claim per product. |
link_reviews_to_claim | header + write | claim_id, reviews[] of {review_id, evidence_quote?, confidence?} (≤50) | {claim_id, reviews[], links_total} — the links written by this call plus the claim's total link count. |
request_review_permission | header + write | review_id, scope (text | photo | both, default both) | {permission_request_id, status}. Consent rules apply: unreachable, opted-out or suppressed reviewers are refused. |
approve_review | header + write | review_id | {review_id, status, stage}. Publishes a pending review in the Inbox (stage needs_review) or a rejected review, exactly like Approve in the app and PATCH /reviews/:id/approve: it can fire your Shopify Flow review-created trigger and Klaviyo review events, and it syncs the review to the product page. A pending review that is still being analysed, with your support team or on hold returns not_in_inbox; already_actioned when it is already published or changed at the same moment. 30 calls/minute per store, shared with reject_review. |
reject_review | header + write | review_id | {review_id, status, stage}. The same moderation action as Reject in the app and PATCH /reviews/:id/reject, for a pending review in the Inbox or a published review. A rejected review is not shown on the storefront and can be approved later. not_in_inbox and already_actioned as for approve_review; shares its 30/minute limit. |
reply_to_review | header + write | review_id, body (1–10,000 chars) | {review_id, reply: {id, body, created_at, updated_at}}. Your public reply, shown under the review. One reply per review: if the review already has one (see reply in list_reviews), this replaces it. HTML is stripped (empty_reply if nothing is left). Same path as PUT /reviews/:id/reply, sharing its 30/minute per-store limit. |
get_optimization | either | product_id | The latest product-page optimization: the five widgets, status, version and the fact-check report. Same body as GET /products/:id/optimization. |
list_creatives | either | channel (ad | email), product_id, limit 1–25 (default 25), offset 0–10,000 | {creatives[], limit, offset, has_more}, newest first. Saved Studio creatives only (not unsaved or dismissed drafts). Each row: id, channel, angle, copy (hook + body for ads, subject + body for emails), proof_quote (the verbatim review sentence), review_id, rating, product_id (bare numeric), product_title, reviewer_display_name (the same public "Jane D." form the review widget shows, or Anonymous — never the full name or email), rights_status, permission_declined, permission_warning (see get_creative), created_at, updated_at. Only creatives whose review is still published (approved and visible) are returned — rejected, hidden or deleted reviews drop their creatives — so the count can be lower than the Studio library's. Reading creatives is free; generating them (generate_creatives or the Studio tab) draws AI credits: 2 per batch, 1 per quote-based call, charged only when the generation delivers a creative, and insufficient_credits at a zero balance. |
get_creative | either | creative_id | One creative in the same shape. permission_warning is {tone, text} (critical when the reviewer declined — a decline resets rights_status to none, so read permission_declined, not the badge), the same warning the Studio editor shows; null once the reviewer has cleared the review). Another store's id, an unsaved draft, or a creative whose review is no longer live is creative_not_found. The Studio write tools act on drafts too, but follow the same rule: a creative that was discarded, or whose review is no longer published, is creative_not_found. |
regenerate_optimization | header + write | product_id, blocks[] (≤5), feedback (≤1000 chars), featured_review_id | The new draft's summary with accepted: true — generation runs in the background. Costs credits past the free regenerations per block; needs an active subscription. featured_review_id requires top_review to be among the blocks (invalid_featured_review_id otherwise); a review that is not eligible leaves the widget empty with a reason in the report rather than failing the call. Only the blocks enabled in the store's ppo_content.enabled_widgets setting are charged; naming a disabled block returns widget_disabled. |
edit_optimization_widget | header + write | product_id, widget_key, content | The updated draft. Edited text is re-fact-checked before it can be published; a byte-identical resubmit changes nothing. removed_on_verify lists, per widget, how many sentences or quotes the check removed and why (inexact_quote, unsupported_claim, fabricated_quote). |
recheck_optimization | header + write | product_id | The draft with a fresh report over the widgets that had not passed. Widgets that already passed are untouched. |
approve_optimization | header + write | product_id | The draft, now approved. Publishing is a separate call. |
publish_optimization | header + write | product_id | The published optimization. Spends credits and writes the live Shopify metafields; refused with unverified_content while any widget has not passed the fact check. omitted_widgets lists the blocks left off the live page and why: insufficient_evidence (too little review evidence) or disabled (turned off in the store's ppo_content setting). |
flag_optimization_widget | header + write | product_id, widget, reason, note | {flagged, refunded} plus the regeneration counters. Always recorded; refunds only when the fact-check report agrees. |
generate_creatives | header + write | channel (required, ad | email), product_id, review_ids[] (≤50). Quote mode instead: review_id + proof_quote | Batch: {mode: "batch", generation_token, status} — the same generation the Studio's Generate button starts; poll it with get_generation. New creatives are unsaved drafts. Quote mode builds creatives around one exact quote (proof_quote must match the review's text character for character, otherwise quote_mismatch), runs synchronously and returns {mode: "quote", status, creatives[]}; it is not available on every store yet (quote_mode_unavailable). Costs AI credits exactly like the Studio tab: 2 per batch, 1 per quote-mode call, nothing when no creatives are produced; insufficient_credits when the store has no headroom. Draws on the 20/hour per-store studio_generate bucket shared with the Studio. |
get_generation | header + write | generation_token | {generation_token, status, channel, creatives[]}. status is pending, running, completed or failed; creatives is filled once completed, in the get_creative shape plus saved. Another store's token is generation_not_found. |
update_creative | header + write | creative_id, copy (hook / body for ads, subject / body for emails) | The creative, with the edit applied and HTML stripped; whether it is saved does not change. The customer quote and the review it comes from are never editable: passing proof_quote, review_id, reviewer_name, proof_rating or channel (at the top level or inside copy) returns immutable_fields; an unknown copy key, or one the channel does not have, returns invalid_copy_fields (nothing is written). |
save_creative | header + write | creative_id, optional copy | The creative, now saved to the Studio library (and returned by list_creatives). Same quote rule as update_creative. |
discard_creative | header + write | creative_id | {creative_id, discarded: true}. The creative leaves the drafts and the library. |
export_creative | header + write | creative_id, format (meta_feed 1080×1350 | meta_story 1080×1920 | google_display), size (square 1200×1200 | landscape 1200×628, Google Display only), acknowledge_permission_warning | The PNG as an MCP image content block (base64, typically a few hundred KB to ~2 MB) plus {creative_id, format, width, height, mime_type, bytes, permission_warning}. Ads only (not_an_ad for emails). When the reviewer has not cleared the review, the export is refused with permission_warning_unacknowledged and the same permission_warning the Studio editor shows, unless you pass acknowledge_permission_warning: true — you're responsible for the ads you run. When the ad was saved in the Studio editor with a review-ad layout (caption for meta_story; stack or grid for meta_feed), the result also carries layout (the layout drawn, or card if it fell back), layout_notice (why, or null) and reviews_used ([{review_id, rights_status, permission_declined}], every review in the image, the creative's own first); the permission check then covers all of those reviews. Every export is logged. Draws on the 60/hour per-store studio_export bucket shared with the Studio. |
The nineteen header + write tools also require the key's Read & Write scope — a Read-only key sees them in tools/list but calling one returns insufficient_scope.
Moderation and replies made through MCP are recorded in the review's audit history as an API-key action, separately from actions taken in the app.
Available over REST only. There are no MCP tools for deleting a review or a reply, review requests, AI review summaries, review groups or ask rules. Use the REST API for those.
Claim, permission, optimization and Studio creative tools are entitlement-gated (claim_collection, rights_management, product_pages, marketing_creatives) like the equivalent REST operations; without the entitlement the tool returns entitlement_required. The Better and Studio plans include them. The Good plan does not: its capped product-page sneak peek covers the REST optimization endpoints only, and its Studio sneak peek is in-app only, so every optimization and Studio creative tool returns entitlement_required on Good. On legacy plans (no longer sold), they are available on Growth and above, and on legacy Pro and Enterprise; stores on the legacy Starter plan do not have them. The Free plan does not include them, and neither does a cancelled store (cancelling returns the store to Free).
Customer text is data
Review content, quotes, reviewer names and creative copy are written by customers or edited by you. The server's initialize instructions tell the client to treat everything a tool returns as data, never as instructions, and never to take reply wording, or the choice of which review to approve, reject or reply to, from what a review says. Keep that rule if you build your own agent on top of these tools.
Errors
Two layers, matching the MCP specification:
- JSON-RPC errors for protocol problems:
-32601unknown method,-32602unknown tool or invalid arguments (wrong type, over-long string, out-of-range number, too many items — checked before any tool runs),-32600for batch arrays or malformed requests,-32700for an empty body. - Tool results with
isError: truefor domain outcomes. The text content andstructuredContentcarry{"error": "snake_case_code"}using the same codes as the REST API:review_not_found,claim_not_found,creative_not_found,claim_archived,product_not_found,another_claim_active,invalid_prompt_text,validation_error,missing_fields(with afieldsarray —upsert_claimcreate needsproduct_id,claim_text,topicandsource),invalid_search,invalid_product_id(list_reviews,top_reviews,list_creatives— not numeric after stripping ashopify-prefix or a product GID),entitlement_required,subscription_required,read_only_token,insufficient_scope(mutating tool with a Read-only key),immutable_fields(product_id/sourcecannot change on a claim update; a creative's quote and review cannot change at all),rate_limited,search_unavailable, thelist_reviewsfilter errorsinvalid_dateandinvalid_date_range, the moderation outcomesnot_in_inbox,already_actioned,moderation_failedandempty_reply, and the permission-request outcomes (no_reachable_email,consent_blocked,suppressed,already_requested). The optimization tools call the same implementation as their REST endpoints, so they answer the same codes:optimization_not_found,optimization_in_progress,optimization_changed,insufficient_credits,credit_limit_reached,unverified_content,invalid_blocks,widget_disabled,invalid_featured_review_id,invalid_widget_key,invalid_content,legacy_draft_regenerateandunpublished_optimization_limit. The Studio tools addgeneration_not_found,generation_failed,quote_mismatch,no_creative,quote_mode_unavailable,conflicting_fields,invalid_copy_fields,permission_warning_unacknowledged,not_an_ad,invalid_format,render_busy,export_unavailable,render_failedandinsufficient_credits.
HTTP-level: 401 bad/expired/revoked key or token, 403 credential without a store, 413 body over 256 KB, 429 rate limited (120 requests/minute per store on each door; top_reviews adds a 60/minute per-store bucket shared with GET /reviews/top). Some tools also draw on per-store hourly buckets shared with the equivalent REST endpoints, so one quota covers both doors: optimization_generate 30/h (regenerate_optimization), optimization_verify 60/h (recheck_optimization and a non-empty edit_optimization_widget), optimization_feedback 20/h (flag_optimization_widget) optimization_publish 30/h (publish_optimization), studio_generate 20/h (generate_creatives, shared with the Studio's Generate) and studio_export 60/h (export_creative, shared with the Studio's PNG export); request_review_permission is capped at 10/minute and 200/day per store, approve_review and reject_review at 30/minute per store together, and reply_to_review at 30/minute per store, shared with PUT /reviews/:id/reply. Exceeding any of these returns rate_limited as a tool result. GET returns 405; DELETE returns 204.
Workflow: does our corpus support this claim?
With the header door connected in Claude Code, a typical exchange is:
search_reviews— "keeps drinks hot for hours", filtered to the product.get_reviewon the promising hits to read the full text.upsert_claim— record the claim with a neutraltopicand exampleask_phrasings.link_reviews_to_claim— attach the supporting reviews with the quoted sentence and a confidence.- Not enough evidence?
set_claim_collectionso the AI review chat can ask happy customers about the topic. Enough?permission_preview+request_review_permissionbefore quoting a review in ads.
See the Claims API for field semantics and the API keys guide for creating and revoking keys.
Book a demo