# WhatWins MCP Agent Guide

Use this guide when an AI agent can call the WhatWins remote MCP server.

## Server

`https://whatwins.io/api/mcp`

Prefer OAuth for remote apps. Static `ww_mcp_` bearer keys are intended for CLI
and raw HTTP clients. Never ask the user to paste a secret into the conversation.

## What the server is for

WhatWins provides read-only, verified market intelligence about competitor ads,
organic posts, traffic, products and shops. It does not create campaigns, change
billing, modify team settings or manage tracked shops through MCP.

## Tool routing

| User intent | Tool |
|---|---|
| Meta or Google paid creative | `search_ads` |
| Instagram, TikTok or YouTube organic post | `get_top_organic_posts` |
| Visits, growth or visitor-market history | `compare_shop_traffic` |
| Active-ad count or live-ad history | `compare_live_ads` |
| Products from known tracked shops | `get_shop_products` |
| Products across the global catalog | `discover_products` |
| Find new shops or competitors by niche | `discover_shops` |
| Positioning, pricing, reviews, socials or tech | `get_shop_overview` |

Do not use `search_ads` for organic TikTok or Instagram posts. Do not use global
discovery when the user explicitly asks about selected tracked shops.

## Safe reasoning rules

1. Preserve source distinctions: Meta, Google, Instagram, TikTok and YouTube are
   not interchangeable.
2. Treat missing or null metrics as unavailable, never as zero.
3. Use WhatWins `firstSeenAt` for ad longevity when present; a platform start date
   may reset on relaunch.
4. Do not infer US Meta reach when it is absent.
5. Keep requests bounded. Start with 6–10 ranked results unless the user asks for
   a different allowed limit.
6. State the requested market, platform, date window and ranking metric in the
   answer so the evidence is auditable.
7. If a private store ID is rejected, ask the user to select or track the shop in
   the connected organization. Never probe IDs from another organization.

## Good prompt decomposition

“Find the longest-running active Meta ads for two brands, then compare traffic”
requires two calls: `search_ads` with `sort=longest`, then
`compare_shop_traffic`. Keep the evidence from each tool separate before writing
the synthesis.

“Find shops selling mushroom coffee, then inspect the strongest one” should call
`discover_shops`, let the user or ranking select a result, and call
`get_shop_overview` only when that shop is available to the connected scope.

## Credits

Credits correspond to verified result rows. A six-ad result costs six credits; a
two-shop comparison costs two. The MCP resource `whatwins://usage` reports the
organization's current shared WhatWins AI balance. When error `-32002` occurs,
reduce the requested result size or tell the user the monthly balance is
insufficient.

## Error handling

- HTTP 401: trigger the client's OAuth connection or ask the user to replace a
  revoked/expired CLI key. Never request the key in chat.
- HTTP 429: wait before retrying; do not loop aggressively.
- JSON-RPC -32602: inspect `tools/list` and correct the arguments.
- JSON-RPC -32002: credit balance is insufficient.
- `isError: true`: report the tool failure; do not fabricate a result.

## Suggested answer shape

1. Lead with the strongest verified finding.
2. Give the ranked evidence with source and date context.
3. Separate observed facts from interpretation.
4. Mention meaningful coverage gaps.
5. Offer one useful follow-up comparison, not an unbounded crawl.

Full reference: https://whatwins.io/mcp/llms-full.txt