Use our AI platform to generate SEO-optimized content
Get 10 FREE articles per month
rank.ai docs

MCP server

Run rank.ai audits and query reports from any MCP-aware AI assistant. Quickstart below.

Quickstart

Three steps. We'll use Claude Desktop as the example; every other host is one or two field-name swaps away.

  1. Generate an API key. Open your account settings → API Keys → New key. Copy the plaintext (you'll see it once).
  2. Add to your MCP config. For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:
    {
  "mcpServers": {
    "rank-ai": {
      "url": "https://api.rank.ai/mcp",
      "headers": {
        "Authorization": "Bearer rnk_live_..."
      }
    }
  }
}
  3. Restart your MCP host and ask your assistant: "Run an audit for fusefinance.com." It'll walk through the conversational flow described below.

Auth

Every request must carry Authorization: Bearer rnk_live_.... Sessions/cookies are not accepted on the MCP endpoint — only API keys minted in your dashboard. Each key is scoped to your org; revoking it is immediate.

Per-user rate limits: 60 req/min and 5,000 req/day across all of your keys. Exceeding either returns a structured error withretry_after_seconds.

The conversational audit flow

Audits aren't fire-and-forget — locations + keywords need confirmation before we charge credits. The MCP models this as an explicit gate. Here's the typical back-and-forth between an LLM and our server:

User: Run an audit on fusefinance.com

Claude calls audit.create(domain: "fusefinance.com")
   → state=scraping

Claude polls audit.next(session_id)
   → state=awaiting_review
     proposed_payload: {
       locations: [...],
       keywords: ["loan origination software", ...]
     }
     credit_cost_estimate: 1200

Claude shows you the proposal, you say "looks good"

Claude calls audit.answer(session_id, payload, confirm=true)
   → state=running

Claude polls audit.next(session_id) until state=complete
   → report_id available

Claude calls report.summary(report_id) and starts answering
"so what's the takeaway?"

Tool reference

Two families. Token costs are advertised in each tool's description so the model can budget. List tools cap default limit at 20 (max 100) with cursor pagination; numeric grids return as histograms unless you explicitly drill into grid_points.

audit.*

audit.create

~200 tok

Start a session. Returns state=scraping plus a session_id. Optional `category` biases keyword extraction.

audit.next

~500 tok

Single source of truth for what to do next. Per-state shapes: scraping → progress; awaiting_review → proposed_payload + schema + credit_cost_estimate; running → progress + report_id; complete → report_id + summary_pointer; failed/cancelled → error_message.

audit.answer

~400 tok

Send `{payload, confirm}`. Validates against the schema returned by audit.next. confirm=false saves the payload but stays in awaiting_review (lets the LLM iterate). confirm=true dispatches the audit and transitions to running — credits are charged here.

audit.cancel

~100 tok

Mark the session cancelled. Idempotent. No-ops on already-terminal states.

audit.usage

~100 tok

Current month's audit-credit balance for the caller. Cheap — call before audit.create when in doubt.

audit.list

~50 tok/row

List the org's recent audit sessions. Optional status filter; cursor pagination keyed on (updated_at desc, id desc).

report.*

report.summary

~800 tok

Always start here. Returns header KPIs (avg gmb/organic rank, review summary), totals, current vs potential estimates, biggest_gap pointer, and next_tools hints.

report.list_keywords

~50 tok/row

Per-keyword aggregation across all locations. Sort by `search_volume` (default), `organic_rank`, `gmb_rank`, or `keyword`. Cursor pagination.

report.list_locations

~40 tok/row

Per-location rows with avg ranks + current/potential lead estimates.

report.location

~2k tok

Single-location detail: rankings dict, lead estimates, review summary. No raw grid points.

report.grid_summary

~200 tok

Bucketed histogram {top_3, top_10, top_20, beyond_20} for one (location, keyword) pair, plus geographic centroid and the worst-ranked point. Always prefer this over grid_points unless explicitly asked.

report.grid_points

~30 tok/pt

Drill-down to individual grid points. `ranks="poor"` (default) returns only points ranking >10. `ranks="all"` returns everything (use limit). Cursor pagination.

report.competitor

~1.5k tok

List competitors with presence counts (sorted by occurrences then leads), or detail for a single domain when `domain` is provided.

report.findings

~2k tok

Enriched findings for non-local site reviews. Optional `severity` filter ("critical"/"needs_work"/"good"). Returns 404 for client-audit reports — those use summary/list_keywords/list_locations instead.

report.insights

~1.5k tok

Pre-computed insight cards: high-volume blind spots, competitor dominance, geographic gaps, quick wins, diminishing returns. Cheap to fetch repeatedly.

national_rank.*

Daily Google SERP position monitoring. Useful for an agent building a "how are my keywords trending?" answer without round-tripping the dashboard.

national_rank.list_keywords

~80 tok/row

List national-SERP keywords being tracked for a website with their latest rank and 30-day trend. Args: website_id (UUID).

national_rank.keyword_history

~30 tok/point

Time-series of rank checks for a tracked keyword. Args: keyword_id (UUID), days (1–180, default 30). Returns daily rank position + ranking URL per day.

ai_rank.*

AI-search visibility — track citations, mentions, and the underlying queries the model issues across ChatGPT, Claude, and Gemini. Designed so an agent can run the entire workflow: discover prompts, track them, fire ad-hoc checks, and pull full run details.

ai_rank.list_prompts

~150 tok/prompt

List AI Rank prompts tracked for a website plus latest visibility per provider (ChatGPT, Claude, Gemini). Args: website_id (UUID). Includes citation_rate and share_of_voice from the most recent 14-day window.

ai_rank.create_prompt

~100 tok

Add a prompt to track. Args: website_id, prompt_text, intent (informational|commercial|navigational|transactional), providers (subset of openai/anthropic/gemini), frequency (daily|weekly|on_demand), samples_per_check (1–10). Charges nothing on creation; daily checks bill the org's credit pool.

ai_rank.run_now

~80 tok

Fire an ad-hoc AI Rank check for a prompt. Each (provider × sample) pair charges 50 credits. Args: prompt_id, providers (optional subset), samples (1–5). Returns enqueued provider list + credits_estimated.

ai_rank.get_run_detail

1k+ tok

Drill into a specific run: answer text, the underlying Google searches the model issued, full citation list with user/competitor flags, and brand mentions. Heavy — use sparingly. Args: run_id.

ai_rank.suggest_prompts

~120 tok/suggestion

Generate 3–20 prompt ideas tailored to the website's industry + tracked SEO keywords. Returns suggestions; does NOT auto-track them. Args: website_id, target_count (3–20).

Example agent prompts

  • "What's our visibility trend in ChatGPT this week?"
  • "Track this keyword in AI Rank too — same providers as the existing ones."
  • "Show me the underlying searches Claude ran for our 'best Botox in Tampa' prompt."
  • "Generate 10 prompt suggestions for our website and add them all."
  • "Run my entire AI Rank set right now and tell me what changed."

FAQ

What's MCP?

Model Context Protocol — Anthropic's open spec for connecting AI assistants to external tools. The rank.ai server speaks the HTTP variant. See modelcontextprotocol.io.

Why API keys instead of OAuth?

Simpler for v1, and the relationship is "your laptop talks to your account" rather than "third party talks to user". OAuth makes sense once we ship to third-party integrations.

What does it cost?

The MCP itself is free for accounts on any plan. Audits charge credits at the same rate as the dashboard. Pricing.

Can I keep grid data out of the LLM context?

Yes — that's the default. Every read tool except grid_pointstrims raw arrays to histograms or aggregates. Drill into points only when the user explicitly asks for them.

Ready to Improve

Your Rankings?

Use our free tools to get instant insights into your SEO performance and discover opportunities to rank higher

Get My Free Audit Report
Get 10 Free Articles