Gentic Support — Documentation

1. Getting Started

Sign Up & Get Your API Key

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

1. Go to gentic.co/support and create an account.
2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
3. 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/support. For Claude Code:

claude mcp add gentic-support \
  --transport http \
  https://mcp.gentic.co/support \
  --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 Support 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/support/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/support/gentic-support.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. Tool Reference

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

5. Pricing

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

6. Notes

• Organization-scoped: the Gorgias, Crisp and Loop Returns connections come from the org's connected integrations (dashboard → Integrations). No credential is ever passed to the tools.
• Loop Returns needs an API key with the **Returns** scope. Loop accepts a key without it, but that key can't read returns — `loop_returns_connection_status` with `check_live: true` reports `scope_missing` for it and `key_not_recognized` for a key Loop rejects.
• Loop Returns is not Loop Subscriptions: the returns tools are `loop_returns_*` here on `/support`; the subscription tools live on `/subscriptions`.
• Cost: `gorgias_sync_tickets` is **1¢ per synced ticket**; `crisp_sync_conversations` is **1¢ per conversation imported**; `search_support_tickets`, `gorgias_sync_status`, `crisp_connection_status`, `loop_returns_sync` and `loop_returns_connection_status` are **free**. Pricing is pulled live from the Gentic MCP manifest.
• `search_support_tickets` only sees tickets already synced into `support_tickets` — run `gorgias_sync_tickets` first, and re-run incrementally to keep results current.
• Tickets are deduped on the Gorgias ticket id: re-syncing an updated ticket refreshes the same row (mutable fields and all) rather than duplicating it.
• For scheduled polling, persist `latest_updated_datetime` and pass it back as `updated_since` — that's the supported incremental pattern.
• Use `search_support_tickets` for 'find/what about' questions and `query_data` over `support_tickets` for counts and aggregations.

7. When to Apply

• User wants to know what customers are complaining about, or the top themes in recent tickets.
• User wants to find support tickets about a specific issue, product, or topic.
• User wants to sync their Gorgias tickets into their Brain for search and analysis.
• User wants to import their Crisp live-chat history so past chats are searchable alongside their tickets.
• User wants to poll for new/updated tickets on a schedule without re-reading the whole backlog.
• User wants to count or aggregate tickets — volume per day, breakdown by status or channel.
• User wants to feed recent support conversations into a digest, triage flow, or product feedback loop.
• User wants to know which products or SKUs get returned most, the top return reasons, or the exchange-vs-refund mix.
• User wants to sync their Loop Returns data into their Brain for analysis.
• User wants to compare returns with the support tickets or Shopify orders of the same customers.

8. Workflow

1. 1. Connect Gorgias once, then sync without credentials

   The Support server sources the Gorgias connection (domain, email, API key) from the org's connected integration (Gentic dashboard → Integrations → Gorgias). You never pass credentials to the tools — connect once in the dashboard and the server reads the encrypted connection automatically. If `gorgias_sync_tickets` reports no connection, point the user to Integrations → Gorgias.

2. 2. Import Crisp chat history with `crisp_sync_conversations`

   If the org uses Crisp, check it first with `crisp_connection_status` (free) — it returns the connected workspace's name and domain so you can confirm it's the right one; if it isn't connected, point the user to Integrations → Crisp. `crisp_sync_conversations` is **1¢ per conversation imported**. It imports chat conversations and transcripts into the same `support_tickets` table as Gorgias, so `search_support_tickets` covers both. It walks the archive newest-first in bounded chunks: call again with the returned `next_cursor` until `has_more` is false. Re-importing a conversation refreshes it rather than duplicating it, and if Crisp rate-limits the import it stops cleanly and resumes from the same point on the next call — nothing is lost or re-charged.

3. 3. Connect Loop Returns once — with the Returns scope

   Loop Returns data comes from the org's Loop Returns integration (Gentic dashboard → Integrations → Loop Returns): an API key generated in Loop Admin → Developer Tools. The key must carry the **Returns** scope — Loop accepts a key without it, but that key can't read any returns. Check with `loop_returns_connection_status` (free) and `check_live: true`: if `problem` is `scope_missing`, tell the user to click the scopes next to the key in Loop's Developer Tools and add Returns (no new key needed); if it is `key_not_recognized`, they need to generate a new key and reconnect it under Integrations → Loop Returns. Loop doesn't say which shop a key belongs to, so no shop name comes back — don't go looking for one. Loop Returns (loopreturns.com, returns and exchanges) is a different company from Loop Subscriptions, whose tools live on `/subscriptions`.

4. 4. Sync returns with `loop_returns_sync`

   `loop_returns_sync` is **free** and read-only. It writes two tables: `loop_returns` (one row per return — state, outcome, totals, order, customer email) and `loop_return_line_items` (one row per returned item — sku, product, `return_reason`, `parent_return_reason`, `return_comment`, outcome), upserted so a re-sync refreshes rows in place. Each call is one bounded chunk and walks all five return states (open, closed, expired, cancelled, review) unless you pass `states`. When `has_more` is true, call again with the returned `next_cursor`, unchanged, and the same `states`. Use `start_from: 'beginning'` (the default) for the first backfill and `start_from: 'warehouse'` on a schedule, so each state resumes where its last complete walk ended. `persisted: false` means a page failed to save — re-call with `next_cursor`, which points at that page. A non-empty `stalled` means a state stopped because Loop's cursor didn't advance: report it to the user rather than calling again.

5. 5. Answer return questions with `query_data`

   Return questions are line-item grained — reason × SKU — so answer them with `query_data` over `loop_return_line_items` (`sku`, `title`, `return_reason`, `outcome`), joined to `loop_returns` on `return_id` = `loop_returns.id` when you need the order or the customer. Join `loop_returns.customer_email` to `support_tickets.customer_email` to see what the same customers told support, and `provider_order_id` to Shopify orders.

6. 6. Sync tickets into the Brain with `gorgias_sync_tickets`

   `gorgias_sync_tickets` is **1¢ per synced ticket**. It pulls tickets updated-ascending with cursor pagination, fetches each ticket's full message thread, and upserts into the per-org `support_tickets` table deduped on the Gorgias ticket id — so a ticket update refreshes the same row rather than creating a duplicate. `limit` (1–100, default 25) caps how many tickets this call gathers; keep batches modest for interactive use since each ticket also incurs a messages fetch and an embedding. Returns `{ tickets, count, latest_updated_datetime, next_cursor, has_more, persisted, embedded }`.

7. 7. Poll incrementally with `updated_since` / `latest_updated_datetime`

   For scheduled or repeat runs, persist the `latest_updated_datetime` returned by each sync and pass it back as `updated_since` on the next run to fetch only tickets changed since the last check. Use `cursor` (a prior call's `next_cursor`) to continue a large backfill in the same session; `has_more` tells you whether another page remains.

8. 8. Search tickets in natural language with `search_support_tickets`

   `search_support_tickets` is **free**. It searches the `support_tickets` table semantically over each ticket's conversation text and returns full ticket rows ranked by relevance — the right tool for 'what are customers complaining about regarding <product>?' or 'find tickets about shipping delays'. Searches only what's already been synced, so run `gorgias_sync_tickets` first if the data may be stale.

9. 9. Narrow with the SQL `filters` clause

   Pass an optional SQL `filters` clause over the structured columns to scope a search — e.g. `status`, `channel`, `customer_email`, `ticket_created_at` / `ticket_updated_at` (TIMESTAMP), `tags` (JSON). Example: `search_support_tickets(query='damaged on arrival', filters="status = 'open' AND ticket_created_at > '2026-06-01'")`.

10. 10. Count and aggregate with `query_data`

    For pure counts or aggregations — ticket volume per day, a breakdown by status or channel — use `query_data` (Gentic Data MCP) over the `support_tickets` table rather than semantic search. Semantic search ranks by relevance; `query_data` is for exact GROUP BY / COUNT analytics over the same rows.

11. 11. Present results clearly

    Don't dump raw JSON. Summarize the tickets — subject, customer, status, and the gist of the conversation — and surface the `count`. After a sync, tell the user how many tickets were `persisted` and `embedded`. For recurring checks, remind the user you'll track `latest_updated_datetime` so the next run only pulls new and updated tickets. For returns, lead with the answer — top SKUs, top reasons, the exchange-vs-refund mix — and say so if the sync stopped with `has_more` still true, since the numbers then cover only part of the history.