ShopVision MCP Server Documentation

Overview

ShopVision is a competitive intelligence platform for ecommerce. It tracks promotional offers, pricing strategies, email campaigns, and advertising across thousands of retail websites.

ShopVision works right inside the AI assistant your team already uses. Once it's connected, ask questions in natural language and get answers grounded in real competitive data — without leaving your assistant.

It runs on the open Model Context Protocol, so it connects to your company's Claude, ChatGPT, or Gemini workspace, as well as developer tools like Claude Code, Cursor, VS Code, and the Gemini CLI.

Features

Promotion Intelligence

Search and analyze promotional offers from your subscribed websites — the same records as the Promotions explorer.

Query promotions by retailer, date range, promotion type, and keywords
Filter by promotion type (sitewide sales, BOGO, gift with purchase, shipping, and more), by who can use the offer (every shopper, new customers, or members), and by the channel it was seen on
Include standing (evergreen) offers alongside time-limited promotions
Compare promotional strategies across competitors

AI Agent

Start conversations with the ShopVision AI agent for deeper analysis.

Analyze ecommerce data, promotions, email campaigns, and ads
Generate reports and summaries from your competitive data
Continue multi-turn conversations for iterative exploration

Account Management

Manage which ShopVision account is active for your session.

Single-account users are scoped automatically
Multi-account users can switch between accounts on the fly

How to turn it on

ShopVision works inside your company's Claude, ChatGPT, or Gemini workspace. It takes one setup step by whoever administers that workspace, and then everyone on your team can use it.

1 Your admin adds ShopVision once

A workspace administrator adds ShopVision a single time, using the setup guide for your tool below. They'll need the ShopVision server URL:

Server URL

https://app.shopvision.ai/api/mcp

Claude (Team & Enterprise)

An owner or admin opens Settings → Connectors in the Claude workspace.
Under the organization's connectors, click Add custom connector.
Enter the name ShopVision and the server URL above, then click Add.

Sign-in uses OAuth, so there's no API key to manage. Once added for the organization, ShopVision appears in every member's Connectors list to switch on. (Individuals on Pro or Max can add it the same way under Settings → Connectors.)

ChatGPT (Business & Enterprise)

A workspace admin opens Settings → Connectors (shown as Apps in newer versions).
Add a custom connector, turning on Developer mode if prompted (available on Pro, Team, Enterprise, and Edu plans).
Enter the name ShopVision and the server URL above, and set Authentication to OAuth.
Publish it to your workspace so members can switch it on.

On first use, ShopVision opens an OAuth sign-in in the browser — no API key required.

Gemini (Gemini Enterprise)

In Gemini Enterprise, a Google Cloud admin adds ShopVision as a Custom MCP Server connector (currently in preview):

In the Google Cloud console, go to Gemini Enterprise → Data stores → Create data store and select Custom MCP Server.
Enter the ShopVision server URL above and set the authentication type to OAuth 2.0.
Enable the ShopVision actions you want available, then save.

Gemini Enterprise needs OAuth connection details (client credentials plus authorization and token URLs) for ShopVision. Contact ShopVision support to get the values for your workspace.

2 You connect in seconds

Open the connectors menu in your assistant, find ShopVision, and sign in with your ShopVision account. That's it — your assistant now has access to your competitive data.

3 Ask

Name ShopVision in your question so your assistant knows to use it. For example:

Try asking

"ShopVision, which of my competitors is discounting hardest right now?"

Tip: if your assistant doesn't pick it up, switch on the ShopVision connector for that chat.

Not the admin for your workspace? Forward this page to whoever manages your company's Claude, ChatGPT, or Gemini. It takes a few minutes to enable for the whole team.

Developer tools

Prefer to connect from a coding tool or the terminal? These clients connect straight to the ShopVision MCP server. On first connect you'll sign in with your ShopVision account in the browser (OAuth 2.0) — there's no API key to manage.

Claude Code

Add the server from your terminal:

claude mcp add --transport http shopvision https://app.shopvision.ai/api/mcp

Then run /mcp inside Claude Code to authenticate (this opens the browser sign-in) and to confirm the server shows as connected.

Cursor

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "shopvision": {
      "url": "https://app.shopvision.ai/api/mcp"
    }
  }
}

Cursor prompts you to sign in through your browser on first use. You can enable, disable, and re-authenticate the server under Settings → MCP & Integrations.

VS Code

Run MCP: Add Server from the Command Palette, or add the server to .vscode/mcp.json in your workspace — note that VS Code uses the servers key and a type field:

{
  "servers": {
    "shopvision": {
      "type": "http",
      "url": "https://app.shopvision.ai/api/mcp"
    }
  }
}

Gemini CLI

Add the server from your terminal:

gemini mcp add --transport http shopvision https://app.shopvision.ai/api/mcp

Or add it to ~/.gemini/settings.json directly:

{
  "mcpServers": {
    "shopvision": {
      "httpUrl": "https://app.shopvision.ai/api/mcp",
      "authProviderType": "dynamic_discovery"
    }
  }
}

Then run /mcp auth shopvision inside Gemini CLI to sign in, and /mcp to confirm the server is connected and list its tools.

Working with multiple accounts

If you have access to multiple ShopVision accounts, the server uses your most recently active account by default. You can switch at any time by asking to "switch to account [name]" or by using account-management tools such as set_active_account when available in your client. If those tools are hidden in your client, contact your ShopVision admin.

Authentication

The MCP server uses OAuth 2.0 with the authorization code flow. When you connect, your client handles the OAuth handshake automatically.

Detail	Value
Protocol	OAuth 2.0 (Authorization Code)
Client Registration	Dynamic (RFC 7591)
Scopes Requested	`profile`, `email`
Token Type	Opaque (instantly revocable)
Discovery	`/.well-known/oauth-authorization-server`

Tokens are opaque (not JWTs), which means they can be revoked instantly if you disconnect or your account status changes. No sensitive data is stored in the token itself.

Tools Reference

list_accounts read-only

Lists all ShopVision accounts you can access. Single-account users are auto-scoped; multi-account users can use set_active_account to choose.

get_active_account read-only

Returns the currently active ShopVision account for your MCP session, or null if not yet set.

set_active_account write

Sets the active ShopVision account for your session. The account persists across tool calls until changed.

Parameters: account_id (required) — must be an account from list_accounts.

list_promotion_types read-only

Returns the promotion types. Each id is a token to pass in query_promotions' promotion_types, with a display name and a description. A promotion can belong to several types: a sale with 0% financing is in its sale type and in Financing & Payment. Free returns and in-store pickup are store policies, not promotions, so no type covers them.

No parameters. It returns these 16 types, in this order:

id	Name	What it covers
`sale_on_sale`	Sale-on-Sale	An extra discount on items already on sale or clearance (“take an extra 20% off sale styles”).
`bogo`	BOGO	Buy one, get one free or discounted.
`multi_buy`	Multi-Buy	Quantity deals other than BOGO (“3 for $30”, “buy 2, get 1 half price”).
`tiered_discount`	Tiered Discount	Discounts that grow with the amount bought or spent (“$10 off $50, $25 off $100”).
`spend_and_save`	Spend & Save	A discount unlocked by spending a minimum amount (“$20 off orders over $100”).
`sale_sitewide`	Sale: Sitewide	A simple discount on everything.
`sale_select_products`	Sale: Select Products	A simple discount on select products or a category.
`sale_single_product`	Sale: Single Product	A simple discount on one product.
`sale_scope_not_stated`	Sale: Scope Not Stated	A simple discount whose copy doesn't say what it applies to.
`sale_services`	Service Offers	A discount on a service, such as installation or alterations.
`gift_with_purchase`	Gift with Purchase	A free gift or sample with a purchase.
`loyalty_subscriber`	Loyalty & Subscriber Offers	Bonus loyalty points or subscription perks.
`shipping`	Shipping	Shipping promotions, where free or discounted shipping is the offer itself. A sale that also ships free is not one.
`financing_payment`	Financing & Payment	Financing offers, such as 0% APR.
`rebates_trade_in`	Rebates & Trade-In	Rebates and trade-in offers.
`other`	Other	Promotions that fit no other type.

query_promotions read-only

Searches the promotions on your account's subscribed websites — the same records as the Promotions explorer. Without query, it returns the promotions matching your filters, most recently seen first, and total_matching is the exact count. With query, it returns the most relevant matches, which is not a count.

By default it returns time-limited promotions open to every shopper: use offer_sets for standing (evergreen) offers and audiences for welcome or member offers. Filter by type with promotion_types (ids from list_promotion_types).

Parameters:

Parameter	Description
`website_urls`	Required. Subscribed websites to search, as they appear in your subscription list. A website you don't subscribe to is refused.
`query`	Optional search text (“labor day”, “free shipping weekend”, “outerwear”). With it, results are the most relevant matches, not a count. Omit it to list every promotion matching the filters.
`start_date`	Start of the date window, ISO-8601 date or datetime. Returns promotions seen at any point on or after it.
`end_date`	End of the date window, ISO-8601. Returns promotions seen at any point on or before it; a bare date includes that whole day.
`promotion_types`	Promotion types to filter by: ids from `list_promotion_types`. A promotion matches when it is in any of them. A sale with 0% financing is in its sale type and in `financing_payment`; `shipping` holds shipping promotions only, not a sale that also ships free.
`offer_sets`	`"limited_time"` (the default): time-limited promotions. `"standing"`: evergreen offers that run continuously (stated as ongoing, seen undated for 30+ days, or a welcome offer that states no timing); the date window does not apply to them. Pass both for everything.
`audiences`	Who can use the offer. Default `["open"]`: offers open to every shopper. Add `"acquisition"` for welcome / new-customer offers, `"membership"` for loyalty / member offers.
`channels`	Only promotions seen on these channels: `website`, `email`, `sms`, `meta_ads`, `google_ads`, `facebook`, `instagram`, `tiktok`, `youtube`, `x_twitter`, `pinterest`, `linkedin`.
`active_only`	Only promotions running now. Default `false` for limited-time offers and `true` for standing offers, whose ended ones (unseen for 90 days, or a welcome offer a newer one replaced) are history. Pass `false` to include those.
`limit`	Number of promotions to return. Default 100, at most 1,000.
`offset`	Number of promotions to skip, to page through results in the same order. `offset` + `limit` may not exceed 2,000: narrow the filters (dates, promotion types, websites) instead of paging further.
`accountId`	Optional. The ShopVision account to search; omit it to use your active account.

Returns data (the promotions), count (how many were returned), total_matching, a message, and warnings when an argument was capped, mapped, or ignored. Each promotion has kind ("promotion"), id, website_url, title, text (the copy as captured), buckets (its promotion types), status (active, ended, evergreen or unknown), is_active, first_seen, last_seen, starts_at, ends_at, observed_channels, audience_gate, promo_code, campaign and citations, plus its offer details (value, scope, eligibility). With query, each also has a relevance score.

Calls written for the previous version of this tool still work for now.

start_chat_run write

Starts a new conversation with the ShopVision AI agent. The agent can analyze your tracked retailers across assortment, pricing, promotions, competitive activity, channel performance, and ad or email campaigns. Returns a thread and run ID for tracking.

The agent uses AI models from third-party providers (currently Anthropic, OpenAI, and Google). Your prompt and the account data needed to answer it are processed by those providers to generate the response.

Parameters: prompt (required), threadId (optional — to continue an existing conversation).

get_chat_run read-only

Gets the status and results of a chat run. Use wait: true to have the server poll until the run completes in a single request, rather than polling repeatedly from the client.

Parameters: threadId (required), runId (required), wait (optional), max_wait_seconds (optional, default 120, max 280).

Usage Examples

Below are example prompts you can use with any MCP-compatible client. The client automatically selects and calls the right ShopVision tools.

Example 1 — Query Recent Promotions

"What promotions are my subscribed retailers running this week?"

Calls query_promotions with your subscribed website URLs and a start_date at the start of the week. Returns the time-limited promotions open to every shopper that were seen this week, most recently seen first — each with its title, promotion types, status, the dates it was seen, and any promo code — and total_matching, the exact count.

Example 2 — Competitive Analysis with AI Agent

"Compare the promotional strategies of two of my competitors over the last 30 days. Which one ran more aggressive discounts?"

Calls start_chat_run to engage the ShopVision AI agent, which analyzes promotion data across both retailers and produces a structured comparison. Then uses get_chat_run with wait: true to retrieve the full analysis in one step.

Example 3 — Discover Promotion Types and Filter

"What types of promotions does ShopVision track? Show me all free shipping promotions from my subscribed sites in the last 7 days."

First calls list_promotion_types, which returns the 16 promotion types (for example Sale: Sitewide, BOGO, Gift with Purchase, and Shipping). Then calls query_promotions with promotion_types: ["shipping"] and a start_date 7 days ago. To include always-on free shipping offers too, it passes offer_sets: ["limited_time", "standing"].

Example 4 — Multi-Turn Agent Conversation

"Analyze email campaign frequency for one of my competitors over the past quarter."
Then follow up: "Now break that down by month and compare it to another competitor."

The first prompt starts a new agent thread via start_chat_run. The follow-up reuses the same threadId to continue the conversation, building on the analysis the agent already produced.

Privacy & Support

ShopVision processes only the data associated with your account and subscribed websites. No data is shared across accounts. OAuth tokens are opaque and instantly revocable.

The data tools (query_promotions, list_promotion_types, and the account tools) only read from ShopVision. start_chat_run sends your prompt and the related account data to the third-party AI providers named above (currently Anthropic, OpenAI, and Google) to generate the answer.

Resource	Link
Privacy Policy	shopvision.ai/legal/privacy-policy
Support	support@shopvision.ai
Website	shopvision.ai