How the MCP server works
Understand the connection lifecycle, tool selection, organization boundaries and verified result model.
WhatWins MCP sits between an AI client and the WhatWins intelligence layer. The AI can inspect a small catalog of tools, choose one for the current question and receive bounded structured evidence.
The request lifecycle
The client connects
Claude, ChatGPT or another client initializes the remote server at https://whatwins.io/api/mcp and negotiates the supported MCP protocol version.
WhatWins authenticates the workspace
OAuth or a static key identifies one organization. Membership, role, plan and revocation status are rechecked for every call.
The client reads the live tool catalog
tools/list returns eight tools with their current JSON Schemas. This is more reliable than a cached or memorized schema.
The model chooses a bounded tool call
The model translates the user's question into explicit filters such as stores, platform, date window, sort and limit.
WhatWins returns verified evidence
The tool response contains structured data, source rows, coverage status and execution metadata. The AI uses that evidence to write its answer.
Tools, not unrestricted database access
The client cannot execute arbitrary SQL or browse internal tables. It can only call the published tools with validated arguments. Limits on store count, date range and result count keep requests predictable and protect shared source systems.
Organization scope
Shop-scoped tools accept stores tracked by the authorized organization. A raw store ID from another organization does not grant access. Global discovery tools search only indexed catalog data and exclude tracked shops where documented.
Verified, partial and unsupported coverage
Every tool result includes a coverage status:
| Status | Meaning |
|---|---|
verified | The requested result is supported by the returned evidence |
partial | Some requested dimensions or sources were unavailable |
unsupported | WhatWins cannot support the requested claim from current data |
An AI client should preserve those boundaries in its answer. “No verified rows” is different from “the thing does not exist.”
Read-only guarantees
The MCP server can research and compare. It cannot:
- add or remove tracked shops;
- change organization settings;
- launch, pause or edit ads;
- publish content;
- contact creators, customers or competitors;
- purchase products or subscriptions.
Continue with Writing good prompts to learn how to get precise, economical results.