MCP server

Last updated 2026-11-04

RankWhy runs a remote MCP server at https://rankwhy.com/mcp (Streamable HTTP). Clients with a browser sign-in connect through OAuth 2.1; clients that only send headers use a key from your account.

1a. Connect with OAuth (Claude.ai, Claude Desktop, ChatGPT, Cursor, Claude Code)

Add https://rankwhy.com/mcp as a remote server; your browser opens RankWhy to sign in and approve the scopes. Discovery is standard: /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server; dynamic registration and client ID metadata documents are both accepted; PKCE S256 is required; tokens last an hour and refresh themselves. In Claude Code: claude mcp add --transport http rankwhy https://rankwhy.com/mcp, then /mcp to sign in. Add the DataForSEO headers the same way when you want Google data.

Scopes: read (stored jobs and runs, free), research (tools that spend on your DataForSEO account or AI credits), write (the writer). A tool answers with the scope it needs when the token lacks it; reconnect to approve more.

1b. Or create a key

Sign in, open your account, Keys tab, choose the scopes and create a key. It starts with rw_ and is shown once; RankWhy keeps only a hash.

2. Add the server with a key

Claude Code

claude mcp add --transport http rankwhy https://rankwhy.com/mcp \
  --header "Authorization: Bearer rw_your_key" \
  --header "X-DataForSEO-Login: you@example.com" \
  --header "X-DataForSEO-Password: your_dataforseo_api_password"

Cursor and other clients with a JSON config

{
  "mcpServers": {
    "rankwhy": {
      "url": "https://rankwhy.com/mcp",
      "headers": {
        "Authorization": "Bearer rw_your_key",
        "X-DataForSEO-Login": "you@example.com",
        "X-DataForSEO-Password": "your_dataforseo_api_password"
      }
    }
  }
}

The DataForSEO headers are needed only for analyze_keyword, cluster_keywords, topic_map and find_weak_spots without URLs. They are passed through for each request and never stored.

Claude Code plugin: the repository ships plugins/rankwhy with the server and a seo-session skill that runs the tools in order (check in, analyze, approve, weak spots, citations, write, prove); claude --plugin-dir ./plugins/rankwhy from a checkout. The server is described for registries in server.json (name com.rankwhy/seo).

Tools

Tool	What it does	Cost
`checkin`	Lists your jobs from the last 24 hours and what to do next. Call it first.	Free
`analyze_keyword`	Google top 20 for a keyword and market, each page read, intent with checked quotes, People also ask. About a minute.	One DataForSEO SERP request on your account; AI free during the beta
`approve_intent`	Confirms the intent and returns the ranking patterns.	AI free during the beta
`get_job`	Shows one job: intent, patterns, cost so far.	Free
`cluster_keywords`	Groups keywords that should share one page (3+ shared top-10 URLs per pair, same intent), with the shared URLs, sibling pages and silos; with demand, adds volume (sum and de-duplicated lower bound), a six-month trend and intent counts per page.	One DataForSEO SERP request per keyword not read in the last 30 days, on your account
`write_article`	Writes a draft from a finished job: outline from the shared headings and People-also-ask gaps, one section at a time, a separate verifier. States only your facts and the consensus facts (numbers three or more ranking sites agree on, each with quote and URL); fetches and checks every link; with your site, suggests internal links from your sitemap.	AI only, free during the beta
`topic_map`	Builds a topical map from a seed: People also ask, related searches and autocomplete suggestions grouped into pages, hub and spokes, core and outer sections by what ranks for each page, bridges to link, gaps nobody answers and a publishing order.	Up to 31 DataForSEO SERP requests on your account, cached ones free
`find_weak_spots`	Checks the top 10 for a keyword (or up to 10 URLs you pass) for weak spots, tiers every domain by referring domains and Open PageRank, and with `site_url` says whether each weak page is within your reach; also what changed since the last check and which pages the AI Overview cites.	One DataForSEO SERP request unless cached, plus one backlink bulk request for domains not seen in 30 days; free with URLs
`check_draft`	Checks a draft against the term ledger of a finished job: terms most ranking pages use that the draft lacks, terms under- or over-used, shared H2 topics without a heading, People-also-ask questions not answered. Three lists, no score.	Free
`outrank_diff`	Places one page of yours on every measured field of the ranking pages (words, headings, tables, FAQ, images, outbound links, schema) with its percentile, the SERP range, the top-3 minimum and the pages above you; differentiators you miss come first. With history, up to four Internet Archive captures say what changed in title, H1 and length over time.	Free (one page read)
`check_citations`	For up to 20 queries, which pages Google's AI Overview and AI Mode cite, whether your site is among them, the most cited domains and the gaps. One sample per query and surface, counts not percentages; every answer is kept.	Two DataForSEO requests per query (about half a cent); cached Google results free
`prove`	Snapshot one page for one keyword (checker, Google position, AI citations, Search Console numbers) and measure it again later: plain before and after, plus which checks were fixed or broke. Panel keys only.	Free; Google and AI Mode rows need the DataForSEO headers
`check_site`	Walks a site from its sitemap and internal links (up to 30 pages here, 100 on the website) and aggregates the page checker: which rules fail on how many pages with examples, duplicate titles and H1s, sitemap pages nothing links to, the weakest pages.	Free
`research_keywords`	Keyword research from one seed (or a * wildcard): DataForSEO suggestions, ideas and related searches, Google autocomplete with question prefixes, People also ask, Google Trends, optionally what the seed’s top pages also rank for and what up to three competitors rank for, joined to your Search Console rows. Every row names its channels and every number its source.	About $0.16 per seed; +$0.36 for also-rank-for, +$0.07 per competitor
`why`	One URL in: picks the keyword (your Search Console or the page’s own rankings), runs the agent on Google’s top 20, places your page on every field of the ranking pages, runs the page checker, tiers the top-10 domains, asks who the AI Overview and AI Mode cite, and returns the verdict with up to seven fixes, each naming the engine and the pages behind it.	2 AI credits; a few cents on your DataForSEO account
`watch`	Keeps a keyword on your watchlist (up to 50, with your site); with refresh, reads every watched keyword now on your DataForSEO account and returns the digest.	Free to add; about $0.002 per keyword on refresh
`digest`	What changed for your watched keywords since the reading a week before: your position, who entered or left the top 10, whether the AI Overview appeared and whether it cites you. The weekly refresh is switched on in your account.	Free
`plan_article`	Puts an article or a page refresh on your calendar for a date; that morning RankWhy runs the agent on the keyword, writes the draft from the facts saved for your site, and creates a WordPress draft when you stored a login. A refresh day also measures your page against the ranking pages and keeps the diff beside the draft.	Free to plan; the run spends 2 credits plus one per section and one SERP on your DataForSEO account
`site_guard`	From your Search Console import: pages earning fewer clicks than their position should (against your own click-through curve, named), their title and description lengths, and queries split between two of your pages with a winner, a redirect list and the stored Google reading.	Free
`guard_fix`	A title and meta description for one page, written from its own text and the queries it is shown for, length-checked. You paste it into your CMS; the next import verifies it.	1 AI credit
`site_memory`	The facts the writer may state about your business for a site, each with the page it was read from or “you”, plus your money pages; with read, it reads your own pages and adds what they state, keeping only facts whose quoted sentence is on the page.	Free to list; 1 AI credit to read
`coverage`	Every keyword your account knows for a site, marked ranking (your Search Console import or a stored Google reading showing your page), drafted, planned or open, grouped into clusters where stored readings share results.	Free
`tasks`	Your task list: what a person must do and no tool can, each with its evidence, filed by Site Guard, Why, the copilot or you.	Free
`file_task`	Files a task for a change no tool can make (apply a fix in your CMS, add a redirect, publish a draft), with the exact change and its evidence.	Free
`prompts`	Your prompt list for a site with the newest reading per surface: whether Google’s AI Overview and AI Mode showed an answer, whether they cited you, which domains they cited, and when.	Free
`track_prompts`	Adds questions to the list and, with read, asks Google for every prompt on your DataForSEO account: one SERP with the AI Overview and one AI Mode answer each.	About $0.003 per prompt on your DataForSEO account
`first_page`	The non-branded page-one queries of your newest Search Console import, with what entered, left or moved against the import before.	Free
`page_function`	Audits one tool page as a tool: whether its working control is in the HTML or only built by JavaScript, how far down it sits, unlabeled fields, numbers without units, the phone viewport, promises against sign-in steps and limits, and your recorded test.	Free (one page fetch)
`page_decisions`	One decision per need your account knows: keep the page that answers it, update an existing page, propose a new page, review a consolidation, out of scope, or unresolved, judged against your confirmed site purpose, with the evidence and what speaks against it.	Free
`site_purpose`	Reads or saves the purpose page decisions judge against: audience, offering, central entity, central intent, core and outer topics, exclusions.	Free
`why_dropped`	When your Google clicks fell, by how much and in what shape, from your Search Console import; then every cause tested against your data and labelled shown, consistent with the date, ruled out, or only you can check (manual actions have no API).	Free
`index_watch`	Google’s URL Inspection readings for the URLs watched on a Search Console property: indexed or not, which left the index, and how many are still indexed after 30 and 90 days. Checks run in your account’s Index tab.	Free
`why_not_indexed`	For the not-indexed watched URLs: the causes with evidence and the fix Google documents (a no-index tag, robots.txt, redirect, canonical, thin or duplicate text, another page already ranking for its words, no referring page, slow server), filed as tasks.	1 credit per run of up to 50 URLs
`indexnow`	Creates and checks your IndexNow key and sends the not-indexed watched URLs to Bing, Yandex, Naver, Seznam, Yep and Amazon. Google does not take IndexNow; the answer code is the result.	Free
`sitemap_audit`	Your sitemap against Google’s rules: lastmod coverage and validity, file limits, the robots.txt line, and which not-indexed watched URLs are missing from it.	Free
`check_page`	SEO, AEO, GEO and trust scores for a URL, top 5 fixes, AI bot access.	Free

Every answer ends with the cost of that call. A key sees only its own account's jobs. Limits are the same as on the website (see pricing).