Cruva MCP and API

The short answer

Cruva offers two ways to connect programmatically:

MCP (mcp.cruva.com) — What it is: A connector that lets your LLM of choice (Claude, ChatGPT, or any other MCP client) read your data and take actions in plain language · Cost: Included on every plan · Best for: Anyone who wants to "talk to" their shop from an AI chat — no code needed

REST API (api.cruva.com) — What it is: A standard HTTP API with an API key · Cost: Separate subscription, $399/month, account-wide · Best for: Building custom dashboards, syncs, or integrations

The MCP being included but the API being a paid add-on is the single most common source of confusion here, so to be explicit: the MCP connector does not require the API subscription. You can connect your LLM to Cruva on any plan.

There is no public webhook / push-event mechanism today.

Connecting Cruva to your LLM (MCP)

This is free and takes about two minutes. In Cruva, the setup guide and connection URL live at Dashboard → MCP (/dashboard/mcp). The URL you'll paste into any client is the same:

https://mcp.cruva.com

Claude setup

Open Claude's connector settings. Go to claude.ai/customize/connectors (or in the Claude app: Settings → Connectors) and click Add custom connector.

Add Cruva. In the dialog, set the name to Cruva and paste the MCP URL from your Cruva dashboard: https://mcp.cruva.com. Click Add.

Connect and sign in. Cruva now appears in your connectors list — click Connect. A window will pop up asking you to sign in to Cruva.

Authorize. Make sure you're logged into the correct Cruva account (agencies: this determines which shops Claude can see), then click Allow access.

You're connected. Open any chat and start prompting — Claude automatically picks the right Cruva tools based on what you ask. You can toggle Cruva on/off per chat from the tools menu in the chat input.

ChatGPT setup

Enable Developer mode. In ChatGPT, open Settings → Security and login and turn on Developer mode. (This is required to add custom MCP connectors — without it the Plugins page won't accept a server URL.)

Add a new plugin. Go to the Plugins page and click the + button.

Configure the connection. In the new plugin dialog:

• Set the name to Cruva
• Paste https://mcp.cruva.com as the Server URL
• Choose OAuth as the authentication method
• Check the confirmation box and click Create

Authorize. You'll be taken to Cruva's authorization screen. Sign in with the correct Cruva account and click Allow access.

Pull in the tools. Back in ChatGPT, Cruva now shows as connected. Click Refresh on the plugin details page to load the full tool list.

Use it in chat. In any conversation, type @Cruva followed by your request to call Cruva tools (e.g. "@Cruva what was my GMV yesterday?").

What you can do with it

Once connected, you can ask your LLM to work across your shop(s) in natural language, for example:

• Performance: "Give me yesterday's recap: affiliate GMV, units, videos posted, top 3 creators, anything unusual vs the 7-day average."
• Creator management: "Find creators who drove over $500 GMV in the last 6 months but haven't posted in 45 days, and draft a re-engagement DM to each."
• Samples: "Review my open sample requests. Approve anyone over 10K followers and over $2K 30-day GMV; reject anyone under 1K followers."
• Agencies: "Switch to Client X and summarize this month's GMV, top creators, and open sample requests in 3 sentences."

Your LLM can both read data and take actions (send DMs, approve/reject samples). Agencies can pivot across all their shops in one conversation.

Connecting other MCP / AI coding tools

mcp.cruva.com also works with other MCP clients beyond Claude and ChatGPT (e.g. via mcp-remote in Cursor and similar tools). Two things trip people up:

• Don't send your REST API key as a Bearer token. That returns an error like expected JWE compact serialization (5 segments), got 1. Instead, either let the client run the normal OAuth sign-in, or use the API-key SSE URL directly: https://mcp.cruva.com/sse?api_key=<your_key>.
• OAuth redirect_uri not allowed? Some tools use a localhost callback that must be allowlisted for your account.

Using the REST API

The REST API is a separate subscription and is account-wide — one subscription covers all your shops.

Get access

Open the API docs at Dashboard → API (or cruva.com/docs/api).

Click API Key & Access. If you don't have a subscription yet, click Subscribe — $399/month.

Once subscribed, click Generate API Key. You can rotate the key at any time. Sub-accounts get their own unique key.

You can also request access by emailing support@cruva.com or via the Cruva Discord.

Authentication

Every request needs three headers:

Content-Type: application/json
x-api-key: <your_api_key>
x-shop-id: <your_shop_id>

x-shop-id is your Cruva internal shop ID, not your TikTok shop ID. Find it at Dashboard → My Shops → shop dropdown → View Info → copy the Shop ID.

Standard vs Enterprise endpoints

Standard endpoints (shop stats, products, affiliates, videos, LIVEs, spark codes, ads campaigns/creatives, samples, messaging, automations) are included in the $399/month subscription.

Enterprise endpoints expose proprietary cross-shop market/creator intelligence and require a separate Enterprise plan. A standard key can't call them — contact sales to upgrade.

Limits

• 50 requests/second and 1,000,000 requests/day per shop. Over that returns 429; back off and retry.
• Pagination depth caps at 10,000 rows — narrow with filters rather than paging deeper.
• Optional idempotency: send an Idempotency-Key header on supported writes; the response is cached for 24 hours so retries don't double-act.

Using an LLM to build against the API? The docs page has an Export to JSON button that downloads the entire spec as one structured file you can hand to Claude, ChatGPT, Cursor, etc.

API & MCP actions are audited

Actions taken through the REST API or through Copilot / an MCP client (like Claude or ChatGPT) are recorded in your audit log, tagged with the API or LLM platform badge — with the API key or MCP tool that did it in the details. Filter the log by platform to see only programmatic activity. See Audit logs: track who did what.

Common problems

"Do I have to pay extra for the API/MCP, or is it in my plan?" The MCP is included in every plan. The REST API is a separate $399/month subscription not included in any plan (including Scale).

"Does the API/MCP connect my LLM for messaging?" Yes — the MCP integration can draft and send DMs and approve/reject samples, not just read data.

"My MCP action failed." First reconnect the connector (re-run the sign-in — in Claude that's at claude.ai/customize/connectors; in ChatGPT, re-authorize the plugin from the Plugins page). If a specific action errors, note the exact wording — it usually points at which parameter or scope is off.

"401 / JWE serialization error when connecting a coding tool." You're sending the REST key as a Bearer token. Use https://mcp.cruva.com/sse?api_key=<key> or let the tool do OAuth instead.