Gentic Reviews — Documentation

Connect any AI agent to your product reviews. Pull your latest Junip reviews — newest-first, incremental since last check — through the Model Context Protocol. Filter by rating, media, or product, and poll for new reviews on a schedule without re-reading the whole backlog.

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Reviews, you need an API key to authenticate your requests.

Go to gentic.co/reviews and create an account.
Create an organization from your dashboard. API keys and billing are scoped to the organization.
Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/reviews. For Claude Code:

claude mcp add gentic-reviews \
  --transport http \
  https://mcp.gentic.co/reviews \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Reviews agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/reviews/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/reviews/gentic-reviews.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. When to Apply

User wants to read their latest product or store reviews.
User wants to poll for new reviews on a schedule without re-reading old ones.
User wants to filter reviews by an exact star rating (1–5).
User wants only reviews that include photos or videos.
User wants reviews for specific products (by store-platform product IDs).
User wants to feed recent reviews into sentiment analysis, support triage, or ad copy.

5. Workflow

1. Connect Junip once, then read without credentials
The Reviews server sources the Junip store key from the org's connected integration (Gentic dashboard → Integrations → Junip). In normal use you never pass `store_key` — leave it unset and the server uses the connected credential. Only pass `store_key` for an ad-hoc/one-off pull against a store that isn't connected in the dashboard yet.
2. Read newest-first with `junip_get_reviews`
`junip_get_reviews` is **5¢ per call (flat)**. With no inputs it returns the newest reviews (default `type: product`, `limit: 50`). Set `type: store` for store-level reviews instead of product reviews. `limit` is 1–250 (default 50) — the tool paginates internally to gather up to that many in one call. Returns `{ reviews, count, latest_id, next_cursor, has_more }`.
3. Poll incrementally with `since_id` / `latest_id`
Junip's v1 Display API has **no date-range filter**, so 'reviews since last check' is done with a high-water mark. Persist the `latest_id` returned by each run, and on the next run pass it back as `since_id` — pagination stops once a review with id ≤ `since_id` is reached, so you only get reviews newer than last time. This is the supported pattern for scheduled/cron polling.
4. Page manually with `next_cursor` / `page_after`
To walk further back through history in one session, pass a prior call's `next_cursor` back as `page_after` to continue fetching older reviews. Omit `page_after` to start from the newest. `has_more` tells you whether another page exists.
5. Filter by rating, media, or product
`rating` maps to Junip's `filter[rating]` and is an **EXACT-match** filter (1–5) — `rating: 4` returns only 4-star reviews, NOT 4-and-up (Junip has no rating-range filter). `media_only: true` returns only reviews with photos/videos. `product_remote_ids` restricts to specific store-platform product IDs (e.g. Shopify product IDs).
6. Present results clearly
Don't dump raw JSON. Summarize the reviews — rating, author, body, product, and any media — and surface the `count`. If `has_more` is true and the user wants more, offer to page with `page_after`. For recurring checks, remind the user you'll track `latest_id` so the next run only pulls new reviews.

6. Tool Reference

4 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

import_amazon_reviews_csv

1¢ / result (min 1¢)

Import a scraped Amazon customer-reviews CSV export into this organization's vendor-neutral `reviews` table (the same table junip_get_reviews / okendo_get_reviews write to; `source='amazon'`, `review_type='product'`). Use this for INDIVIDUAL Amazon reviews (reviewer, title, body, star rating, date) — these come from scraped CSV exports because Amazon's SP-API does not expose individual reviews. (The Amazon MCP's sync_amazon_reviews is different: it stores Amazon's AGGREGATED review-topic insights in a separate `amazon_review_topics` table.) Provide the CSV via EITHER `csv_url` (an https URL — a presigned-S3 link, a public Google Sheets URL, or a Google Drive share link; auto-converted to the direct CSV and fetched server-side) OR inline `csv_content` — exactly one. Expected columns (case-insensitive, extra columns preserved verbatim in `raw`): Date, Date Only, Reviewer Name, Verified, Title, Body, Rating, URL, Review ID, Images, Videos, Product Code, Variation / ASIN, Style. Optionally add a `Product Title` (or `Product Name`) column — it's mapped to `product_title` and folded into the embedding so reviews can be found by product name (not just ASIN). Each review is upserted deduped on its Amazon Review ID (re-importing the same export is idempotent; mutable fields refresh) and its title+body embedded so it's searchable via `search_reviews` and aggregatable with `query_data` over the `reviews` table. Returns `{ imported, skipped, total, latest_created_at, persisted, embedded, source, table }`. Billed 1¢ per review imported (covers the per-row embedding).

Parameter	Type	Description
`csv_url`	`string`	HTTPS URL to the Amazon reviews CSV. Accepts a presigned S3 link, a public Google Sheets URL (e.g. https://docs.google.com/spreadsheets/d/<id>/edit?gid=<tab> — the gid/tab is preserved), or a Google Drive share link (/file/d/<id>/view, open?id=, uc?id=) — Sheets/Drive are auto-converted to the direct CSV export. The sheet/file must be shared 'Anyone with the link can view'. Fetched server-side over https only; resolves to a public address (internal/private hosts rejected). Provide this OR csv_content, not both.
`csv_content`	`string`	The raw CSV text of the export, inline (header row + data rows). Provide this OR csv_url, not both. For large exports prefer csv_url.

junip_get_reviews

5¢ / call

Fetch reviews from Junip (v1 Display API), newest-first, with cursor pagination and incremental-since support. Sources the Junip store key from the org's connected integration; pass `store_key` only to override. Every fetched review is also upserted into the org's `reviews` table in MotherDuck (deduped on the Junip review id; mutable fields like response/votes/featured/rating are refreshed on re-pull), and the tool returns the persisted rows for this pull — including `review_created_at` / `review_updated_at` and `ingested_at` — newest-first. For scheduled polling, persist the returned `latest_id` and pass it back as `since_id` on the next run to fetch only newer reviews (Junip has NO date-range filter, so this high-water-mark pattern is the supported way to get 'reviews since last check'). For manual paging, pass the returned `next_cursor` back as `page_after`. Respects Junip's 2 req/sec rate limit. Returns `{ reviews, count, latest_id, next_cursor, has_more, persisted, table }`; if the MotherDuck write fails the call still returns the freshly-fetched reviews with `persisted: false`. $0.05 per call.

Parameter	Type	Description
`store_key`	`string`	Optional Junip store key override. Prefer leaving this unset — the server uses the org's connected Junip credential. Only pass for ad-hoc/one-off pulls against a store not yet connected in the dashboard.
`type`	`string`	Which Junip endpoint to read: 'product' reviews (default) or 'store' reviews. enum: product, store
`limit`	`integer`	Max reviews to return this call (1–250, default 50). The tool paginates internally to gather up to this many. 1 – 250
`since_id`	`integer`	High-water mark. Pagination stops once a review with id ≤ this is reached, so only reviews newer than `since_id` are returned. Pass the previous run's `latest_id` here for incremental scheduled polling. max 9007199254740991
`page_after`	`string`	Raw Junip cursor for manual pagination — pass a prior call's `next_cursor` to continue fetching older reviews. Omit to start from the newest.
`rating`	`integer`	Maps to Junip `filter[rating]` — an EXACT-match filter (1–5). e.g. `rating: 4` returns only 4-star reviews, NOT 4-and-up. Junip's v1 Display API has no rating-range filter. 1 – 5
`media_only`	`boolean`	When true, maps to Junip `filter[media_only]` — only reviews with photos/videos.
`product_remote_ids`	`string[]`	Maps to Junip `filter[product_remote_ids]` — restrict to these store-platform product IDs (e.g. Shopify product IDs).

okendo_get_reviews

5¢ / call

Fetch product & store reviews from Okendo into this organization's vendor-neutral `reviews` table (the same table junip_get_reviews writes to; `source='okendo'`). Uses the org's connected Okendo integration (dashboard → Integrations; the Okendo User ID is configured there once, like an API key — it is NOT a tool input). Walks NEWEST-FIRST with cursor pagination — ONE walk covers both: incremental polling (pass the previous run's `latest_created_at` as `since` to fetch only newer reviews — Okendo has NO date-range filter, so this high-water-mark pattern is the supported 'reviews since last check') and full historical backfill (omit `since`, then keep passing the returned `next_cursor` back as `cursor` until `has_more` is false). Optionally restrict to one product via `product_id` (numeric Shopify product id). Each review is upserted deduped on the Okendo reviewId (mutable fields refreshed on re-pull) and its text embedded so it's searchable via `search_reviews`; aggregate with `query_data` over the `reviews` table. Returns `{ reviews, count, latest_created_at, next_cursor, has_more, persisted, embedded, table }`; if the DB write fails the call still returns the freshly-fetched reviews with `persisted:false`. $0.05 per call.

Parameter	Type	Description
`limit`	`integer`	Max reviews to return this call (1–250, default 50). The tool paginates internally (Okendo caps each page at 25) to gather up to this many. 1 – 250
`since`	`string`	High-water mark — an ISO-8601 datetime (pass the previous run's `latest_created_at`). The newest-first walk stops once it reaches a review created at/before this, so only newer reviews are returned. Omit for the first/full pull or for backfill.
`cursor`	`string`	Resume cursor — pass a prior call's `next_cursor` (an Okendo `nextUrl`) to continue the same walk. The primary control for backfill: keep passing it back until `has_more` is false. Omit to start from the newest review.
`product_id`	`string`	Optional — restrict to one product's reviews by numeric Shopify product id (e.g. '6998274998307').

search_reviews

Free

Search this organization's product & store reviews by natural language — the right tool for 'what do customers love about <product>?', 'what are people unhappy about?', 'find reviews mentioning battery life'. Searches the `reviews` table (populated by okendo_get_reviews / junip_get_reviews, across all connected review sources) semantically over each review's product+title+body text, returning full review rows ranked by relevance. Supports an optional SQL `filters` clause over the structured columns to narrow results — e.g. rating, source, product_title, review_created_at (TIMESTAMP), verified_buyer, review_type. Example: search_reviews(query='stopped working after a month', filters="rating <= 2 AND review_created_at > '2026-01-01'"). For pure counts/aggregations (average rating, review volume per month, rating distribution), use query_data over the reviews table instead.

Parameter Type Description

Parameter	Type	Description
`query` required	`string`	Natural-language search query, e.g. 'comfortable and easy to use' or 'complaints about shipping damage'.
`filters`	`string`	Optional SQL filter clause (the body of a WHERE) over structured columns: rating, source, review_type, product_id, product_title, review_created_at, review_updated_at, verified_buyer, would_recommend, has_media. Read-only; write/file functions are rejected. Example: "rating <= 2 AND verified_buyer = true".
`limit`	`integer`	Number of reviews to return (1–50, default 10). 1 – 50

query

required

string

Natural-language search query, e.g. 'comfortable and easy to use' or 'complaints about shipping damage'.

filters

string

Optional SQL filter clause (the body of a WHERE) over structured columns: rating, source, review_type, product_id, product_title, review_created_at, review_updated_at, verified_buyer, would_recommend, has_media. Read-only; write/file functions are rejected. Example: "rating <= 2 AND verified_buyer = true".

limit

integer

Number of reviews to return (1–50, default 10).

1 – 50

7. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

Tool	Cost
import_amazon_reviews_csv	1¢ / result (min 1¢)
junip_get_reviews	5¢ / call
okendo_get_reviews	5¢ / call
search_reviews	Free

8. Notes

Organization-scoped: the store key comes from the org's connected Junip integration. Pass `store_key` only to override for an unconnected store.
Cost: `junip_get_reviews` is a flat **5¢ per call** regardless of how many reviews come back or how many internal pages are fetched to satisfy `limit`.
Reviews are always returned newest-first. For 'since last check', persist `latest_id` and pass it as `since_id` next run — there is no date-range filter in Junip's v1 Display API.
`rating` is exact-match, not and-up. To approximate 'and-up', call once per star value you care about.
Respects Junip's 2 req/sec rate limit; the tool handles internal pagination within that budget.