Skip to Content

For agents

How AI agents use PeekRank over MCP: connecting, the server's own instructions, and the rules for billed tools.

If you're an AI agent (or you're building one), start here. This is how PeekRank expects to be used over MCP, and the guide the server itself gives every client when it connects.

Connect

  • Server URL: https://app.peekrank.io/mcp (Streamable HTTP).
  • Sign in with OAuth (the client discovers it from the server's 401), or send a workspace API key as Authorization: Bearer lk_live_…. Details: Connect your AI assistant and Sign-in, API keys and access.
  • Every tool, its inputs and its price: MCP tools.

What the server tells your agent

These are the server's instructions, sent with every connection:

PeekRank is an SEO workspace: projects (a domain + tracked keywords with weekly rank checks), saved tool runs, AI visibility and spend.
- Free tools read data PeekRank already stored — use them first. Start with get_seo_snapshot (every project at a glance, with what needs attention); find resolves a name to an id; diagnose_keyword explains why one keyword moved. Then list_projects → get_project → whats_changed / get_keyword_history / get_domain_metrics; list_runs → get_run re-reads any past research, domain overview, gap, backlinks or audit at no cost (get_run filters a domain overview's keywords too). get_workspace = your role, plan and team; get_budget = the balance.
- Site audits run in the background: start_site_audit (billed) returns an audit_id; get_site_audit (free) waits up to 50 s per call and returns the score and issues when the crawl is done.
- Write tools (when listed) set up tracking: create_project, add_keywords (each tracked keyword is checked automatically and billed per check), remove_keywords, archive_project, set_up_prompt_tracking, archive_prompts. Confirm with the user before adding many keywords or prompts, or archiving.
- Billed tools (when listed) fetch FRESH data and are paid for from the workspace's PeekRank balance (this month's free data first). Each description says what it costs. Pass max_cost_usd ≥ the stated max; check get_budget first when running several. Prefer re-reading a recent run with get_run over paying again; check_rankings re-checks many keywords for less than scan_keyword.
- Workspace management (when listed, owners/admins who allowed it): manage_team, share_link, set_report_branding, revoke_connection. Always ask the user before using them — they change who can see the workspace's data. Paying is never done by an assistant: create_top_up_link returns a page where the person pays.
- Positions: 1 = top of Google; null = not in the top 100. A positive change = moved UP.
- AI visibility (Prompt Tracking): get_ai_visibility shows whether ChatGPT, Gemini, Google AI Mode and Perplexity name the project's brand for its prompts (position = place among the brands an answer names); get_ai_answer reads one answer; get_ai_sources lists the sites they cite; get_ai_overviews covers Google's AI Overview on tracked keywords. check_ai_prompts (billed) asks again — the interface engines answer within minutes, read them later with get_ai_visibility.

Rules worth knowing

  • Read before you pay: get_seo_snapshot, find, list_runs and get_run are free and usually answer the question.
  • Billed tools need max_cost_usd ≥ the maximum their description states. A lower value is a free quote: the call is refused and says what it would cost.
  • get_budget says how much the workspace can still spend today, and how much this connection may spend.
  • Positions: 1 is the top of Google; null means not in the top 100; a positive change means it moved up.
  • Never pay for the person: top-ups are always done by a human on PeekRank's payment page.

On this page