Pacvue MCP

Generate Pacvue ad reports from any MCP client. We focus on Cursor, Claude (Code & Desktop), and ChatGPT, and support any other agent that speaks the Model Context Protocol.

One MCP server, no per-tool wiring.

Enterprise-managed clients (Claude, ChatGPT, and similar): where connectors are governed at the workspace level, individual users may not be permitted to add Pacvue MCP as a Custom Connector. Please contact your IT administrator to have it provisioned for your organization.

What you get

Report MCP covers all retailers your Pacvue account has access to. New retailers and new fields are picked up automatically — no MCP-side changes. Data Query MCP and SOV Query MCP run on the same retailer footprint and the same Console permission model — entitlements decide which tools and platforms appear in the agent’s list.

Choosing the right toolset

One toolset per task. Pick a flow and stay in it — agents shouldn’t mix Report calls with Data Query or SOV Query calls in the same job.

Retailer support

The matrix below shows which retailers each toolset covers. The actual list returned to your agent is scoped to your Pacvue Console entitlements — you only see retailers and tools you have access to.

Specific report types, levels, and schemas are discovered at runtime via fetch_report_list, fetch_query_list, and fetch_query_schema. There’s no static list to keep in sync — when Pacvue adds a retailer or a field, your agent picks it up on the next call.

Notes per toolset

• Report MCP — covers the retailers marked ✓ above (14 product lines). Amazon Commerce reports are split between Vendor (1P) and Seller (3P) via the channel field on each report entry. Walmart Commerce and Target Commerce are not available in Report MCP. Use fetch_report_list to see the full report catalog for a retailer at runtime.
• Data Query MCP — wired for 16 platforms. Scope keys differ by retailer:
  • Standard ads & commerce → profileIds (resolve via materialType=profile)
  • Amazon DSP → advertiserIds (resolve via materialType=advertiser)
  • Amazon Commerce → split into commerce-amazon-vendor and commerce-amazon-seller platform keys (different from the Report MCP commerce + channel model — pick the right key)
  • Walmart Commerce → commerce-walmart-vendor (Vendor 1P only); resolve scope via materialType=vendor_account → profileIds. See Walmart Commerce Data Query scope below.
  • Target Commerce → commerce-target (Vendor 1P only); scope is your Pacvue client and is applied automatically — no material lookup needed. See Target Commerce Data Query scope below.
• SOV Query MCP — 11 platforms. Amazon and Walmart support full deviceMode; the other nine are Aggregated only. Keyword tag filters work on amazon / walmart / instacart / criteo (brand & keyword tabs). Walmart-only zip_code filter; instacart / criteo / citrus / doordash use store (retailerIds).

Amazon Commerce Data Query scope

What’s available in Data Query per Amazon Commerce channel:

Manufacturing vs. Sourcing view (1P): Vendor Sales and Inventory default to the Manufacturing view. Switch Sales to Sourcing via options.reportType (e.g. sourcing_retail); Inventory exposes both views as separate measure sets. Both are discoverable through fetch_query_schema.

Vendor (1P) and Seller (3P) route to different backend services — commerce-amazon-vendor and commerce-amazon-seller. Pick the right platform key when calling execute_query.

Walmart Commerce Data Query scope

Walmart Commerce is wired into Data Query for Vendor (1P) only, under the commerce-walmart-vendor platform key. What’s available:

Resolve scope via materialType=vendor_account → pass IDs in execute_query.profileIds. Only Vendor (1P) is supported — Walmart Seller (3P) commerce is not available in either Data Query or Report MCP.

Target Commerce Data Query scope

Target Commerce is wired into Data Query for Vendor (1P) only, under the commerce-target platform key. What’s available:

Scope is your Pacvue client and is applied automatically from your credential — no fetch_query_materials call and no profileIds needed. Target Commerce is not available in Report MCP.

Endpoint

https://mcp.pacvue.com/mcp

All tools — Report MCP, Data Query MCP, and SOV Query MCP — are exposed under one server entry. You do not configure them individually. The agent will only see the toolsets your account is entitled to.

Authentication

Pacvue MCP reuses Pacvue’s existing OAuth 2.0 system — both auth options below resolve to a real Pacvue user, and data access is scoped to that user’s Console entitlements.

You’ll need from your Pacvue admin (or yourself, if you have access):

• A Pacvue Console account, and one of:
  • An API Token (for clients that don’t support browser-based OAuth), or
  • An MCP client that supports OAuth 2.0 with Authorization Code Flow + PKCE (most modern clients do).

Option A — API Token (recommended for headless/CLI clients)

1. Sign in to the Pacvue Console.
2. Go to Settings → MCP → Create API Token.
3. Give it a name, pick an expiry (max 180 days), click Create.
4. Copy the token immediately. The full value (pv_...) is shown only once. After you close the dialog only the masked prefix remains visible.
5. Paste it into your MCP client config as the value of the Authorization header — no Bearer prefix, just the raw token (see Client setup).

To rotate or revoke a token, return to the same page and delete the row. Up to 50 active tokens per user. Tokens are stored hash-only — Pacvue cannot recover a lost token.

Option B — OAuth 2.0 (browser login)

For clients that support OAuth 2.0 with Dynamic Client Registration (DCR) — Cursor, Claude Code, Claude Desktop, ChatGPT, and most other modern MCP clients.

1. In your client’s mcp.json, add the server URL without any headers block.
2. The client opens your default browser on first connection, you log in to Pacvue and click Authorize.
3. The browser redirects back to the client over a loopback URL; the client receives an access token + refresh token and the connection is live.
4. Refresh token has a 7-day sliding window — every refresh resets the TTL. After 7 days of no use, you’ll be asked to log in again.

To revoke a session, go to Settings → Connected Apps in the Pacvue Console and remove the client. Each device produces its own entry, so you can tell “Cursor on work laptop” from “Cursor on home laptop”.

Client setup

The Authorization header takes the raw token — no Bearer prefix.

Cursor

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

OAuth (recommended):

{
  "mcpServers": {
    "pacvue-mcp": {
      "url": "https://mcp.pacvue.com/mcp"
    }
  }
}

API Token:

{
  "mcpServers": {
    "pacvue-mcp": {
      "url": "https://mcp.pacvue.com/mcp",
      "headers": {
        "Authorization": "pv_"
      }
    }
  }
}

Claude Code

OAuth:

claude mcp add pacvue-mcp --transport http https://mcp.pacvue.com/mcp

API Token:

claude mcp add pacvue-mcp \
  --transport http \
  --header "Authorization: pv_" \
  https://mcp.pacvue.com/mcp

Or in .claude/settings.json:

{
  "mcpServers": {
    "pacvue-mcp": {
      "type": "http",
      "url": "https://mcp.pacvue.com/mcp",
      "headers": {
        "Authorization": "pv_"
      }
    }
  }
}

Claude Desktop & Claude (claude.ai)

Recommended: Custom Connector (OAuth, no config files)

Both Claude Desktop and Claude on the web support adding remote MCP servers as Custom Connectors — no mcp.json, no Node.js, no npx. This is the simplest and most reliable path, and it’s what we recommend.

Enterprise-managed clients: see the note at the top of this README — provisioning of the connector may require your IT administrator or workspace owner.

1. Open Settings → Connectors → Add custom connector.

• In Claude Desktop: click your name in the lower-left → Settings → Connectors.
• In Claude on the web: profile menu → Settings → Connectors.

2. Fill in:

• Name: Pacvue MCP (or whatever you like)
• Remote MCP server URL: https://mcp.pacvue.com/mcp

3. Click Add, then Connect. A browser tab opens for Pacvue OAuth — sign in and click Authorize.
4. Back in Claude, the connector flips to Connected and the 5 Report MCP tools become available immediately. No restart needed.

This uses OAuth, so connections drop after 7 days of inactivity and you’ll be asked to re-authorize. To revoke, remove the connector in the same UI, or remove the device entry under Settings → Connected Apps in the Pacvue Console.

Why this is preferred: Custom Connectors talk to the MCP endpoint natively over HTTP. The mcp-remote bridge (below) is only needed if you specifically need API Token auth, or if your Claude Desktop version is too old to expose the Connectors UI.

---

Alternative: mcp-remote bridge (required for API Token auth)

If you need to authenticate with an API Token (headless usage, CI, shared machines, or any case where browser OAuth isn’t an option), use the [mcp-remote](https://www.npmjs.com/package/mcp-remote) stdio bridge.

Prerequisites: Node.js (LTS, includes npx) installed and on your PATH.

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

You can open it directly from Claude → Settings → Developer → Edit Config.

API Token, macOS / Linux:

{
  "mcpServers": {
    "pacvue-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.pacvue.com/mcp",
        "--header",
        "Authorization: pv_"
      ]
    }
  }
}

API Token, Windows:

{
  "mcpServers": {
    "pacvue-mcp": {
      "command": "npx.cmd",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.pacvue.com/mcp",
        "--header",
        "Authorization: pv_"
      ]
    }
  }
}

Note (Windows): Use npx.cmd rather than npx — Claude Desktop on Windows spawns the command directly without a shell, so the .cmd extension is required.

After saving the config, fully quit and relaunch Claude Desktop (close the tray icon too — a window close is not enough). The pacvue-mcp entry should appear under Settings → Developer as running, and the 5 Report MCP tools should be available in chat.

ChatGPT

ChatGPT uses OAuth only — it does not accept custom HTTP headers, so API Token isn’t an option here.

1. Open Settings → Connectors → Add custom connector.
2. Server URL: https://mcp.pacvue.com/mcp.
3. Sign in via the browser flow when prompted.

Other MCP clients

Pacvue MCP is a standard streamable-HTTP MCP server, so any compliant client (VS Code GitHub Copilot, Windsurf, Cline, custom in-house agents, …) can connect with the same two patterns above:

• OAuth — point the client at https://mcp.pacvue.com/mcp with no headers.
• API Token — point the client at the same URL and add an Authorization header containing pv_ (raw token, no Bearer prefix).

If your client expects a different config schema, consult its docs — the URL, the optional header, and the header value are the only Pacvue-side knobs.

Verify

Fully quit and restart your MCP client (a window reload is not enough for some clients). The pacvue-mcp entry should switch to Connected and the tool list should appear.

Then ask your agent:

What Pacvue tools do you have access to?

You should see up to 12 tools across three toolsets:

• Report MCP — 5 tools
• Data Query MCP — 5 tools
• SOV Query MCP — 2 tools

Tools you don’t have entitlements for won’t appear in the agent’s tool list — that’s expected, not a misconfiguration.

Tool reference

You don’t call these directly — your agent picks them. They’re listed here so you know what Pacvue MCP can do, and so you can sanity-check the agent’s plan in transcripts.

Report MCP (5 tools)

Canonical flow: fetch_report_list → fetch_report_schema → (fetch_materials if filters) → run_report → fetch_report_result.

Data Query MCP (5 tools)

Canonical flow: list_query_platforms → fetch_query_list → fetch_query_schema → (fetch_query_materials for scope/filter IDs) → execute_query.

Wired query platforms (16): amazon-ads, amazon-dsp, walmart, instacart, target, kroger, criteo, citrus, bol, chewy, samsclub, doordash, commerce-amazon-vendor, commerce-amazon-seller, commerce-walmart-vendor, commerce-target.

Scope rules — execute_query requires a non-empty scope, resolved via fetch_query_materials (Target Commerce is the one exception — its scope comes from your credential):

• Standard ads & commerce → materialType=profile → pass IDs in execute_query.profileIds.
• Amazon DSP → materialType=advertiser → pass IDs in execute_query.advertiserIds.
• Amazon Commerce → materialType=vendor_account (1P) or seller_account (3P), IDs go in profileIds. Vendor and Seller route to different backend services — pick the right one. See Amazon Commerce Data Query scope above for what’s available per channel.
• Walmart Commerce → commerce-walmart-vendor (Vendor 1P only) → materialType=vendor_account, IDs go in profileIds. See Walmart Commerce Data Query scope above.
• Target Commerce → commerce-target (Vendor 1P only) → no material lookup; scope is applied automatically from your credential. See Target Commerce Data Query scope above.

Walmart and Target commerce support Vendor (1P) only, via Data Query (commerce-walmart-vendor / commerce-target). Their Seller (3P) commerce is not supported, and neither is available in Report MCP.

SOV Query MCP (2 tools)

Canonical flow: list_sov_material → query_sov.

Wired SOV platforms (11): amazon, walmart, instacart, target, kroger, criteo, citrus, bol, chewy, samsclub, doordash.

Required query_sov parameters: platform, tab (brand | keyword | asin), categoryIds, startDate, endDate. Optional: startCompare / endCompare, dim, deviceMode, brands, keywords, keywordTagIds, pageInfo, columns. Metrics include shareOfShelf, paidSOV, organicSOV, spSOV, sbSOV, and tab-dependent top-N matrices.

Platform-specific notes:

• Amazon & Walmart — full deviceMode (Aggregated / Separated / Mobile / PC / App). Other nine platforms support deviceMode=Aggregated only.
• Keyword tags — amazon, walmart, instacart, criteo (brand & keyword tabs). Use leaf tag IDs in query_sov.
• Walmart-only — zipCodes filter via materialType=zip_code.
• **instacart / criteo / citrus / doordash** — retailerIds via materialType=store.
• **sov_group / sov_keyword_tag** — name search isn’t supported; pick IDs from the full list.

In-chat vs. file: query_sov returns a paginated table inline — for spreadsheets / multi-tab ZIPs use Report MCP’s SOVReport (the ASIN-Keywords tab requires filters.sovBrands, max 100 brands).

Example prompts

Report MCP — async export:

Export last month's Walmart Campaigns where Spend > $500.
Columns: campaign name, impressions, clicks, spend, ACoS.
Send me the download link when it's ready.

Export last month's Amazon Campaigns to a CSV I can share.

Data Query MCP — inline metrics in chat:

Using Pacvue Data Query, show last 7 days Amazon campaign spend, ROAS, and impressions
by day for my main profile.

Using Pacvue Data Query, top 10 Amazon DSP line items by sales last month for advertiser X.

SOV Query MCP — Share of Voice in chat:

Using Pacvue SOV, show brand-level share of voice for my US beverage category last month —
break down paid vs organic.

Using Pacvue SOV, top 20 keywords by share of shelf for my Walmart juice category last week.

The agent will discover the schema at runtime, ask you to confirm any destructive parameters, and poll until the file is ready (Report MCP) or return rows directly in the thread (Data Query / SOV Query).

Troubleshooting

My browser opened to the Pacvue MCP gateway page

The gateway URL is an MCP endpoint, not a webpage. If it opened in your browser, your client tried to authenticate, failed, and fell back to the URL because no OAuth flow was available. Almost always this means the API token in mcp.json is missing, expired, or revoked.

Fix one of two ways and fully restart your MCP client afterwards (a window reload is not enough for some clients):

• Use a token — make sure headers.Authorization in mcp.json contains a current pv_... token (raw token, no Bearer prefix). Generate or rotate one under Settings → MCP.
• Use OAuth instead — remove the headers block from mcp.json entirely. The client will show a real Connect button that opens the Pacvue login page.

Claude Desktop shows pacvue-mcp as failed / not connected (mcp-remote path)

If you went with the Custom Connector approach, you shouldn’t hit any of these — connector errors usually surface as a clear message in the Connectors UI. The items below apply when you’re using the mcp-remote bridge:

• **npx not found** — Node.js isn’t installed or isn’t on PATH. Install Node LTS, restart Claude Desktop.
• Wrong command on Windows — use npx.cmd, not npx. Claude Desktop spawns the command directly without cmd.exe, so the extension matters.
• Header has Bearer prefix — the token must be raw (Authorization: pv_...), no Bearer.
• Stale OAuth cache — when switching between OAuth and API Token (or rotating tokens), clear mcp-remote’s cache: delete ~/.mcp-auth (macOS/Linux) or %USERPROFILE%\.mcp-auth (Windows), then restart.

To see the underlying error, check Claude Desktop’s MCP logs at ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows).

If the bridge keeps misbehaving, the simplest fix is usually to remove the mcpServers entry from claude_desktop_config.json and switch to the Custom Connector path described above.

Connection drops after a week of inactivity

Expected — OAuth refresh tokens have a 7-day sliding window. Reconnect through the browser flow and you’re good for another 7 days. To eliminate the prompt entirely, switch to an API token.

run_report failed with a missing-required-field error

The agent skipped a required filter or config. Required fields are enforced upstream by the platform’s own API, not by the MCP layer. Re-run the request and tell the agent which platform / profile / time range you want — that’s usually the missing piece.

Data Query tools don’t show up

Data Query MCP is available to any Pacvue user — there’s no special entitlement to enable. If the tools don’t appear, it’s almost always a connection or auth issue: fully restart your MCP client and confirm your token / OAuth session is valid. The tool list is also scoped to the retailers your Console account can see, so you’ll only get platforms you have access to.

execute_query rejected with empty profileIds / advertiserIds

execute_query needs a non-empty scope. Resolve scope IDs first via fetch_query_materials (materialType=profile for standard ads; materialType=advertiser for Amazon DSP; materialType=vendor_account / seller_account for Amazon and Walmart Commerce). Tell the agent the profile / advertiser / account name and let it look up the IDs. Target Commerce is the exception — its scope comes from your credential, so this error there points to an auth issue rather than a missing lookup.

Agent mixed Report and Query calls in one task

Agents should pick one toolset per task — Report MCP or Data Query MCP or SOV Query MCP. If you see run_report showing up in the middle of a Data Query flow (or vice versa), restate the intent (“answer in chat” vs. “give me a file”) and start a fresh turn.

Security & limits

• All credentials (API tokens, OAuth access + refresh tokens) are stored hash-only on the server.
• Each credential is bound 1:1 to a Pacvue user. Data access is scoped to that user’s Console entitlements.
• Issuance, use, and revocation are written to an audit log.
• Revocation is immediate — the next request with a revoked credential is rejected.
• Transport is TLS-only. Do not put pv_... tokens into chat history, screenshots, or shared configs.