# For agents (/reference/agents)

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](/ai/connect/) and
  [Sign-in, API keys and access](/ai/access/).
- Every tool, its inputs and its price: [MCP tools](/reference/mcp-tools/).

## What the server tells your agent

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

```text
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.