Cruva API, MCP & the Claude integration

For developers and power users who want to pull Cruva data, or drive Cruva from Claude and other AI tools.

The short answer

Cruva offers two ways to connect programmatically:

• MCP (mcp.cruva.com) — What it is: A connector that lets Claude (and other MCP clients) 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 Claude — 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 use Claude with Cruva on any plan.

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

Connecting Cruva to Claude (MCP)

This is free and takes about two minutes. In Cruva, the setup guide and connection URL live at Dashboard → MCP (/dashboard/mcp).

1. In Claude, go to claude.ai/customize/connectors and click Add custom connector.

2. Name it Cruva and paste the URL: https://mcp.cruva.com. Click Add.

3. Click Connect, sign in to your Cruva account, then click Allow access.

4. You're connected. Start prompting.

What you can do with it

Once connected, you can ask Claude 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."

Claude 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 (e.g. via mcp-remote). 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

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

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

3. 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 sam@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, Cursor, etc.

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 Claude for messaging?" Yes — the Claude (MCP) integration can draft and send DMs and approve/reject samples, not just read data.

"My Claude/MCP action failed." First reconnect the connector (re-run the sign-in at claude.ai/customize/connectors). 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.