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.

The ShopVision MCP server lets you query your ShopVision data directly from any client that supports the Model Context Protocol — including Claude.ai, Claude Desktop, Claude Code, Cursor, and VS Code. Ask questions in natural language and get answers grounded in real competitive data.

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

Getting Started

Server URL

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

1. Connect

Add the server URL above to your MCP client. In Claude.ai, use the Connectors menu. In Claude Desktop, Cursor, or VS Code, add it to your MCP server configuration.

2. Authenticate

When you connect for the first time, you'll be redirected to sign in with your ShopVision account. After authorizing, you're connected — the OAuth token is managed automatically.

3. Start Asking Questions

Once connected, just ask questions in natural language. Your MCP client will call the appropriate ShopVision tools behind the scenes.

If you have access to multiple ShopVision accounts, the server will use your most recently active account by default. You can switch accounts 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 MCP 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