# WhatWins MCP — Self-Contained Reference

Endpoint: https://whatwins.io/api/mcp
Protocol: remote HTTP MCP using JSON-RPC 2.0
Access: WhatWins Pro and Business
Purpose: read-only ad, organic, traffic, product and shop intelligence

## Authentication

OAuth is preferred for Claude App, ChatGPT and other remote MCP apps. WhatWins
supports Authorization Code + PKCE, dynamic client registration, refresh tokens
and explicit organization selection.

Protected-resource metadata:
https://whatwins.io/.well-known/oauth-protected-resource

Authorization-server metadata:
https://whatwins.io/.well-known/oauth-authorization-server

CLI clients may use:
Authorization: Bearer ww_mcp_your_token

Static keys are organization-scoped, stored as SHA-256 hashes, revocable and
shown only once. Never expose a key in a conversation or URL.

## Connection guides

Claude App:
1. In WhatWins organization settings, select Claude app.
2. Click Connect to Claude.
3. Add the prefilled connector with OAuth fields empty.
4. Sign in to WhatWins, choose an organization, allow access.

ChatGPT:
1. On ChatGPT Business or Enterprise/Edu web, open Settings → Apps → Advanced settings.
2. Enable Developer mode and choose Create app.
3. Name it WhatWins; server URL is https://whatwins.io/api/mcp.
4. Choose OAuth, scan tools, create, then approve the WhatWins consent screen.

Claude Code:
claude mcp add --transport http --scope user whatwins https://whatwins.io/api/mcp --header "Authorization: Bearer ww_mcp_your_token"

## Tools

search_ads
- Searches verified Meta and Google creatives.
- storeIds: 0–5. Empty IDs require a concept for global discovery.
- query limit is bounded by the live schema.
- Filters: source, ISO country, format, placement, active status, sort, date,
  language and CTA.

get_top_organic_posts
- Ranks Instagram, TikTok and YouTube posts.
- storeIds: 0–5. Empty IDs require a concept.
- Sort: views, likes, comments, shares, saves, engagement or outlier.
- Optional 1–365 day window.

compare_shop_traffic
- 1–5 tracked store IDs.
- 1–36 months.
- Returns current and historical visits and available market mix.

compare_live_ads
- 1–5 tracked store IDs.
- Platform: all, Meta or Google.
- 1–36 months of observed/reconstructed history.

get_shop_products
- 1–5 tracked store IDs.
- Up to 20 products with stock, price, product-type and sort filters.

discover_products
- Global indexed product query, 2–120 characters.
- Up to 12 results with stock, price and sort filters.

discover_shops
- Global specialist-shop query, 2–120 characters.
- Up to 8 results with country, minimum traffic, minimum live ads, Shopify-only
  and ranking filters.

get_shop_overview
- 1–5 tracked store IDs.
- Returns available positioning, markets, pricing, reviews, socials, pixels,
  apps, catalog and freshness context.

The `tools/list` result is the authoritative JSON Schema.

## Resources

whatwins://usage
- JSON snapshot of the selected organization's shared WhatWins AI credit balance.

## Metering

Credits are actual verified result rows, not requests. Tool execution reserves a
maximum, then settles against returned rows. Empty and failed results do not
become fake billable data.

## Limits and errors

- HTTP 401: missing/expired/revoked token, disabled OAuth client, lost org
  membership, insufficient role or plan. Response includes WWW-Authenticate.
- HTTP 429: credential, organization or daily MCP limit reached.
- -32600: invalid JSON-RPC request.
- -32601: method not found.
- -32602: invalid tool arguments.
- -32002: insufficient monthly AI data credits.
- MCP `isError: true`: execution failed after a valid call.

## Data semantics

- Missing remains missing; never coerce null to zero.
- Prefer WhatWins first-seen history for ad longevity.
- Do not infer reach for US Meta ads when unavailable.
- Preserve platform and source in summaries.
- Raw tracked-store IDs are limited to the connected organization.

Agent routing guide: https://whatwins.io/mcp/agent-guide.md
Product overview: https://whatwins.io/llms-full.txt