MCP SETUP GUIDE

Connect Rankwize to your AI client.

Generate an API key, add the Rankwize MCP server to Claude Desktop, Cursor, Claude Code, or any MCP-compatible client, and ask your citation, prompt, and effectiveness data in plain language. Read-only by default. Included on Pro and above.

What is MCP?

The Model Context Protocol (MCP) is Anthropic's open standard for letting an AI assistant call tools on your behalf. The Rankwize MCP server exposes your monitoring, diagnosis, and search data as a set of tools. Your assistant fetches the tool schemas on connect and routes your natural-language questions to the right calls — you never write a query or export a CSV.

The server is a pull surface. Eight tools read your data; two write tools require explicit write scope on the key. A read-only key can never change your workspace.

Before you start

•A Rankwize workspace on Pro or above (Track or Diagnose). MCP is not included on Free or Watch.
•An MCP-compatible client — Claude Desktop, Cursor, Claude Code, or another that supports remote MCP servers.
•For the GSC and GA4 tools, the corresponding integration connected in Rankwize.

Generate an API key

In Rankwize, go to Settings → API Keys. Choose Create API key, give it a label that identifies the client or agent (for example "Claude Desktop — work"), and assign a scope:

readAll eight read tools. The default.
writeAdds create_prompt and trigger_run. Opt in only if your client needs to make changes.

The raw key is shown once and starts with rwz_live_. Copy it immediately — it is hashed at rest and cannot be recovered. Use one key per client so you can revoke selectively.

Add the server to your client

The server URL is https://api.rankwize.io/mcp. Authenticate either by signing in (OAuth, where the client supports it) or by passing your API key as a Bearer token. Client UIs change quickly — if a step looks different, check your client's own MCP-connector docs; the URL and auth below stay the same.

Claude Desktop

Open Settings → Connectors → Add custom connector and paste the server URL. Claude Desktop connects over OAuth, so you sign in to Rankwize in the browser — no API key or config file needed.

Cursor

Add Rankwize to your mcp.json (Settings → MCP), using the HTTP transport and your API key:

{
  "mcpServers": {
    "rankwize": {
      "type": "http",
      "url": "https://api.rankwize.io/mcp",
      "headers": {
        "Authorization": "Bearer rwz_live_YOUR_KEY"
      }
    }
  }
}

Claude Code

Add the server from the CLI with the HTTP transport:

claude mcp add --transport http rankwize \
  https://api.rankwize.io/mcp \
  --header "Authorization: Bearer rwz_live_YOUR_KEY"

ChatGPT desktop (preview) and other clients

Add Rankwize as a connector via ChatGPT's Developer Mode using the same server URL — no portal registration required. Any client that speaks remote MCP works: point it at https://api.rankwize.io/mcp and pass your key as a Bearer token (the generic JSON config above applies).

Ask

Your assistant fetches the tool schemas on connect. Ask a question in plain language and it routes to the right tool calls — for example, "Which of my prompts are invisible on Perplexity, and which competitor gets cited instead?"

Tools reference

Ten tools — eight read, two write. You don't call these directly; your assistant does. The example shows a question that routes to each.

list_prompts

Tracked intents with current citation status per platform.

Ask: "Which of my prompts are invisible on Perplexity?"

get_prompt_detail

Factor scores, citation history, matched page, and current recommendation for one prompt. Diagnosis fields require +Diagnose.

Ask: "What's the citation history and recommended fix for my 'best AI visibility tool' prompt?"

get_content_library

Your indexed content pages with fingerprint data.

Ask: "Which of my indexed pages cover competitor-comparison topics?"

get_topic_effectiveness

Effectiveness scores by topic, fix type, and platform. +Diagnose only.

Ask: "What's my citation rate by fix type over the last 90 days, and which is weakest?"

get_run_summary

Results from recent monitoring batch runs.

Ask: "Summarize last week's runs grouped by platform."

get_top_queries

Top organic search queries from Google Search Console. Requires the GSC integration.

Ask: "Which of my top GSC queries are not yet cited by any AI platform?"

get_top_landing_pages

Top landing pages by organic performance from GSC, each flagged for whether it is tracked in Rankwize.

Ask: "Show my top organic landing pages and which ones I am not yet tracking."

get_ai_referral_traffic

AI-platform referral traffic from Google Analytics 4. Requires the GA4 integration.

Ask: "How much traffic did ChatGPT and Perplexity refer last month?"

create_prompt write scope

Add a new prompt intent to your tracking queue.

Ask: "Add 'enterprise AEO platform comparison' to my tracked prompts."

trigger_run write scope

Enqueue an on-demand monitoring batch.

Ask: "Run a fresh citation check on my top prompts now."

Worked examples

Find traffic you are invisible to AI on

Ask for your top organic GSC queries, cross-reference them against your tracked prompts, and surface the high-impression queries with invisible status on ChatGPT, Perplexity, and Google AI Overviews.

get_top_querieslist_prompts

Target the next content sprint

Pull effectiveness by fix type over the last 90 days and rank the underperformers, so the next sprint goes where the citation needle actually moves.

get_topic_effectiveness

Post a weekly standup summary

Summarize last week's runs by platform and — paired with a Slack MCP server — drop the summary into your standup channel without anyone opening Rankwize.

get_run_summary

Add a prompt and check it immediately

Create a new prompt intent, then trigger an on-demand run to get a first citation read without waiting for the next scheduled batch. Requires a key with write scope.

create_prompttrigger_run

Rate limits and units

Two layers protect your account: request rate limits and a monthly MCP unit allowance per workspace. On a limit you receive a 429 — back off and retry after the window rather than hammering.

60 requests / minute

per API key. Protects against runaway agent loops.

5,000 requests / day

per API key. Daily ceiling per key.

50 trigger_run / day

per workspace. Shared with the in-app "Run Now" counter.

200 requests / minute

per IP. Anti-abuse ceiling across keys from one address.

Each workspace also has a monthly MCP unit allowance shared across all its keys, resetting on the 1st of each month (UTC). Most read calls cost 1 unit; heavier reads and create_prompt cost 5; trigger_run costs 100 (one full citation check across your monitored platforms). See the MCP overview for the per-plan allowances.

Troubleshooting

401

Unauthorized

Cause: Missing, malformed, or revoked key. The header must be exactly Authorization: Bearer rwz_live_… — a valid key starts with rwz_live_.

Fix: Re-check the header and that the key is still active in Settings → API Keys. Generate a new key if it was revoked.

403

Forbidden

Cause: Your plan does not include MCP (Free and Watch do not), you called a +Diagnose tool on a Track-only plan, or you used a write tool with a read-only key.

Fix: Upgrade to Pro or above, add Diagnose for diagnosis tools, or create a key with write scope.

429

Too Many Requests

Cause: You hit a per-minute / per-day rate limit, or your workspace exhausted its monthly MCP unit allowance.

Fix: Back off and retry after the window. Unit allowances reset on the 1st of each month (UTC). Slow your agent's polling or upgrade for a larger allowance.

—

Connection refused / cannot connect

Cause: Wrong URL, or a client that does not support the Streamable HTTP transport.

Fix: Confirm the URL is https://api.rankwize.io/mcp and that your client supports remote MCP over Streamable HTTP, then restart the client.

Security and key management

One key per client

Label each key by client or agent so you can revoke one without disrupting the others. Keys are scoped to a single workspace.

Read-only by default

Write scope is opt-in at key creation. A read-only key cannot create prompts or trigger runs, even if asked.

Hashed at rest, shown once

The raw key is displayed a single time at creation and stored only as a hash. If you lose it, revoke it and create a new one.

Audited and revocable

Every call is recorded with the tool name, key label, and outcome (90-day retention). Revoke any key from Settings → API Keys; it stops working immediately.

Your visibility data, where you already work.

Included on Pro and above. Read-only by default.