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.

Query promotions by retailer, date range, promotion type, and keywords
Filter by specific promotion categories (coupons, free shipping, BOGO, etc.)
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 all available promotion types with their IDs, names, and descriptions. Use this to discover valid promotion type IDs for filtering in query_promotions.

query_promotions read-only

Searches for promotional offers from your subscribed websites. Supports filtering by website URLs, promotion types, date ranges, and keyword queries.

Key parameters: website_urls (required), website_mode (required: individual or group), query, promotion_type_ids, start_date, end_date, include_permanent, limit, offset.

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.

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 date range covering the current week. Returns matching promotional offers including coupon codes, sale events, and free shipping thresholds.

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 to show available categories (e.g., coupons, free shipping, BOGO, clearance). Then calls query_promotions filtered to the free shipping type ID and a 7-day date window.

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.

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