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 · 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 · Best for: Building custom dashboards, syncs, or integrations.

The MCP and APIs are included on every plan · 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 included on every plan and is account-wide: one set of keys can cover every shop on your account.

Where to find it

In Cruva, open Dashboard → API (cruva.com/dashboard/api). That's where you manage your API keys, and it shows the full API reference with your own key and shop ID pre-filled in the examples.

The same reference is also public at cruva.com/docs/api, so you can send it to a developer who doesn't have a Cruva login.

Create an API key

1. Go to Dashboard → API and click API Keys & Access at the top of the left sidebar.
2. Click Create API Key.
3. Give the key a Key name that describes what it's for (e.g. "Reporting integration" or "Looker sync"). Names can be up to 100 characters.
4. Choose what the key can reach (see the next section). If you leave both settings on their defaults, the key gets full access.
5. Click Create Key. It appears in your key list right away. Use the eye icon to reveal it and the copy icon to copy it.

Keys look like cruva_ followed by 64 characters. You can create up to 50 keys per account, so it's worth giving each integration its own key. That way you can lock it down, rotate it, or revoke it without breaking anything else.

Control what a key can access

Each key has two settings, and each one is either All or Restrict:

• API routes: All routes lets the key call every endpoint, including endpoints we add later. Restrict lets you tick only the endpoints it needs. They're grouped by category (shop stats, affiliates, samples, messaging, automations, etc.), and you can select or clear a whole group at once. A read-only reporting key, for example, only needs the GET endpoints it actually uses, so it can't send DMs or approve samples.
• Shops: All shops lets the key work with every shop on your account, including shops you link later. Restrict limits it to the shops you tick. This is useful for agencies giving a client or contractor a key that only works for their own shop.

A request outside a key's access is rejected, even if the key itself is valid. Each key in the list shows badges like All routes / 3 routes and All shops / 2 shops, so you can see its access at a glance (hover the shop badge to see which shops).

To change a key's access later, click the pencil icon (Edit access) on the key, adjust it, and click Save Changes. The key value stays the same, so you don't need to update anything in your integration.

Enterprise endpoints appear under a separate Enterprise API heading in the route picker. Ticking them on a key doesn't grant Enterprise access by itself. Your account also needs an Enterprise plan (see below).

Rotate a key

If a key may have leaked (it was committed to a repo, shared in a chat, or a team member who had it leaves), rotate it:

1. In API Keys & Access, click the refresh icon (Rotate key) on that key.
2. Click Confirm Rotate.

Rotating issues a new key value with the same name and access settings. The old value stops working immediately, so update your integration with the new key straight after rotating.

Delete a key

Click the trash icon (Delete key) and then Confirm Delete. The key stops working right away and can't be recovered. If you only need a new secret, rotate the key instead.

Sub-accounts

Every user, including sub-accounts, has their own API keys. A sub-account's keys belong to that sub-account, not the parent account, and they can only reach the shops that sub-account can already see.

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 and copy the Shop ID. It's also shown at the top of the API Keys & Access dialog for the shop you currently have selected. One key works with any shop it has access to, so you change shops by changing x-shop-id, not the key.

Standard vs Enterprise endpoints

Standard endpoints (shop stats, products, affiliates, videos, LIVEs, spark codes, ads campaigns/creatives, samples, messaging, automations) are included in every Cruva plan.

Enterprise endpoints expose proprietary cross-shop market/creator intelligence and require a separate Enterprise plan. A key can't call them unless your account is on that plan, even if the key's route access allows them. Contact sales to upgrade.

Limits

• 10 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 (in the dashboard and at cruva.com/docs/api) 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 account's Activity Logs, 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 Activity Logs: see who did what in your account.

Common problems

"Do I have to pay extra for the API/MCP, or is it in my plan?" The MCP and the standard REST API are included in every plan. If you still have the old standalone API subscription in billing, you can cancel it from Billing & Plans. The enterprise data is not included in any plan (including Scale) and requires speaking with our sales team.

"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.

"A request is rejected even though my key is valid." The key's access is probably restricted. Open Dashboard → API → API Keys & Access, click the pencil icon on the key, and check that both the endpoint and the shop in your x-shop-id header are allowed. If it's an Enterprise endpoint, your account also needs the Enterprise plan.

"My integration stopped working after someone rotated the key." Expected. Rotating invalidates the old value immediately. Copy the new value from API Keys & Access into your integration.