Serpy: lời nhắn cài đặt cho AI agent. Dán toàn bộ vào agent (Claude Code, Hermes Agent, Codex, Cursor…), nó sẽ tự kết nối Serpy để kiểm tra thứ hạng Google.

You are setting up serpvn for me and then working with it. serpvn tracks where a domain ranks on Google (Vietnam by default) for keywords: one-off searches, and projects of keywords checked together on a schedule. Do every step below yourself, without asking me unless a step truly needs me.

My serpvn API key: <YOUR_KEY>
MCP server: https://serpy.datlab.dev/mcp (Streamable HTTP; every request sends the header Authorization: Bearer <key>)
REST API: https://serpy.datlab.dev/v1, the same key; OpenAPI: https://serpy.datlab.dev/v1/openapi.json; this guide: https://serpy.datlab.dev/mcp.txt

The key is a secret. Keep it only in your client's MCP config or in an environment variable (SERPVN_KEY). Never print it back in full (say sv_ab12…), never write it into a repository, a project file or a commit.

## 1. Register the MCP server where you run
Work out which agent or client you are running in and add serpvn there, user-wide (not in a project's files):

### Claude Code (Chạy trong terminal (mọi dự án: --scope user))
claude mcp add --scope user --transport http serpvn https://serpy.datlab.dev/mcp --header "Authorization: Bearer <YOUR_KEY>"

### Cursor (~/.cursor/mcp.json)
{
  "mcpServers": {
    "serpvn": {
      "url": "https://serpy.datlab.dev/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_KEY>"
      }
    }
  }
}

### Claude Desktop (claude_desktop_config.json (Settings › Developer › Edit Config))
{
  "mcpServers": {
    "serpvn": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://serpy.datlab.dev/mcp",
        "--header",
        "Authorization:${SERPVN_AUTH}"
      ],
      "env": {
        "SERPVN_AUTH": "Bearer <YOUR_KEY>"
      }
    }
  }
}

### Codex (~/.codex/config.toml)
# export SERPVN_KEY=<YOUR_KEY>   (in ~/.zshrc or ~/.bashrc)
[mcp_servers.serpvn]
url = "https://serpy.datlab.dev/mcp"
bearer_token_env_var = "SERPVN_KEY"

### Hermes Agent (~/.hermes/config.yaml)
mcp_servers:
  serpvn:
    url: "https://serpy.datlab.dev/mcp"
    headers:
      Authorization: "Bearer <YOUR_KEY>"
    timeout: 180

### Khác (any other client)
{
  "mcpServers": {
    "serpvn": {
      "type": "http",
      "url": "https://serpy.datlab.dev/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_KEY>"
      }
    }
  }
}

A client that only speaks stdio: run it through mcp-remote as in Claude Desktop above.

## 2. Verify
List the tools (tools/list): serpvn has 33. Then call usage. If your client cannot load a new MCP server without a restart, do not stop: use the REST API now for this session (below) and tell me to restart the client to get the MCP tools.

REST fallback (curl, JSON; header Authorization: Bearer $SERPVN_KEY):
- GET https://serpy.datlab.dev/v1/usage: Credits that can be spent now (left = allowance, the plan's credits left this month, which lapse at its end, + credits, those bought, which never expire), credits used this month, the price (cost.page: credits a page of results of one keyword), the plan's limits and whether searching goes on now
- POST https://serpy.datlab.dev/v1/search: Search one keyword now (first in the queue); with wait, the result when done in time, else 202 and the id to poll
- GET https://serpy.datlab.dev/v1/search/{id}: A search's state (queued, running, done, failed, cancelled), its times and, once done, its result
- POST https://serpy.datlab.dev/v1/track: As the app's Kiểm tra: keywords into their site's project (made when missing) and checked now; with no site at all, searched as a batch
- GET https://serpy.datlab.dev/v1/projects: Projects with their summary (top 3/10/30, average, up/down) and the check going on (run)
- GET https://serpy.datlab.dev/v1/projects/{id}: A project and its keywords (position, previous, best, url, trend), filtered and sorted; counts: how many keywords each choice of a filter gives among those the other filters leave (a group's all: the group; the outer all: every keyword); run: the check going on (done, left, current, eta)
- POST https://serpy.datlab.dev/v1/projects/{id}/check: Check every keyword of a project now as one check (its keywords × its pages in credits, refused whole past the balance); follow it with the project (run)
- GET https://serpy.datlab.dev/v1/keywords: Keywords searched, the latest first: position, previous, best, url, trend of the last 12 checks
- GET https://serpy.datlab.dev/v1/keywords/{id}/history: A keyword's checks, the latest first: its positions over time; full adds each check's results
Every call and its parameters: https://serpy.datlab.dev/v1/openapi.json

## 3. Self-check and report
Make one cheap read that spends no searches (usage, then list_projects) and tell me in a few lines: which client you configured and where the key is kept (masked), how many tools you see, the searches left this month and my projects.

## 4. Working with serpvn
Tools:
- check_rank: Check where a domain ranks on Google for one keyword (or up to 500), searched now, first in the queue.
- get_search: Poll one search by id: its state and, once done, its position and results.
- list_searches: The customer's queue: searches waiting and running (with how many are ahead), then the latest ended; or one batch's searches with their positions, filtered like a project.
- cancel_searches: Cancel waiting searches: one (id), a batch, or all.
- promote_searches: Move waiting searches (one id, or a batch) to the front of the queue.
- track_keywords: Track keywords for their sites: each site's project is made (or added to) and checked now, as the app's Kiểm tra.
- list_keywords: Keywords searched so far, the latest first, with position, previous, best, url and trend; query filters by keyword or domain.
- get_keyword: One keyword (by id from list_keywords) with its latest check in full: the Google results.
- keyword_history: A keyword's positions over time (its checks, newest first); full adds each check's Google results.
- list_checks: Checks newest first, filtered by keyword, domain, country, language, or a competitor domain found in the results.
- get_check: One check in full: the position and every Google result it read (the SERP snapshot).
- list_projects: Projects with their summary (keywords, top 3/10/30, average position, up/down, last check) and the check going on (run); next_run (ms): the next scheduled check, when a schedule is on.
- get_project: One project: its keywords with position, previous, best, url and trend, filtered (top, band, found, state, move, q) and sorted (order); counts for every filter; run: the check going on (done, left, current keyword, eta; auto when its schedule started it); next_run: its next scheduled check (ms) and results_at, about when that check's results are in (ms; an estimate).
- create_project: Create a project for a domain, with keywords, country, language, pages, schedule and the email when a check ends.
- update_project: Change a project's title, domain, subdomains, country, language, pages, schedule (off, daily, weekly, days; with days 1 Monday to 7 Sunday, hour 0-23 and minute 0-59 in the customer's time zone; no minute: serpvn picks one of that hour few projects use) or where each check is told when it ends (notify_channels: email, telegram, zalo, each set up in the settings first; notify_done false turns all off).
- delete_project: Delete a project.
- restore_project: Bring back a project deleted moments ago (within the undo window).
- add_keywords: Add keywords to a project, in its country and language or those given.
- remove_keywords: Remove keywords from a project; their waiting searches are cancelled, their history stays.
- import_keywords: Read keywords from CSV text (a keyword column and maybe a domain one, by header or the first two columns) or plain lines.
- check_project: Check every keyword of a project now, as one check (its keywords × its pages in credits; refused whole past the balance; not while a check goes on).
- recheck_keywords: Search some keywords of a project again, or failed: true for those that failed in its latest check; first in the queue, one search each.
- stop_check: Stop a project's check now: keywords not searched yet are set aside and not counted; results so far are kept.
- resume_check: Go on with a stopped check of a project (its stopped keywords cost their credits again).
- project_days: A project day by day: keywords checked, found, top 3/5/10/30 and the average position each day it was checked (a report over time).
- export: A report as compact rows (columns + rows), as the CSV/Excel export has them, plus the /v1 URL of the file (CSV, XLSX, or TXT for a project; it needs the same Authorization header).
- usage: The credits that can be spent now (the plan's of this month, then those bought), used this month, the price (credits a page of results), the plan's limits, the API rate and whether searching goes on now.
- credit_history: The credit ledger, newest first: top-ups, each check (searches and credits given back), trial, the plan's monthly credits, the admin's adjustments; filter all, topup, spend, other.
- locales: The country and language pairs that can be searched (vn/vi by default).
- get_notifications: The notification settings: email and its address, Telegram, Zalo, the rank-change threshold, time zone, weekly report, long-check email.
- update_notifications: Change notification settings (only the fields given).
- test_notifications: Send a test notification to each channel on (5 a day).
- resend_confirmation: Mail the confirmation link to the notification address waiting again.

Rules:
- Every search costs credits: one credit a page of results it reads (10 results), so a keyword at the default 1 page costs 1, at 3 pages (top 30) 3; a project check costs its keywords × its pages. The plan's credits of the month go first, then those the customer bought; reading results, projects and history costs nothing; searches that fail or are cancelled before they are searched give their credits back. Call `usage` before large batches and tell the user what a batch will cost (e.g. 120 keywords × 3 pages = 360 credits).
- For a site's keywords, prefer a project: `track_keywords` (or `create_project` + `check_project`) checks them all as one check; avoid many one-off `check_rank` calls for the same keywords.
- A check or search that is still running is followed, never started again: poll `get_project` (its `run`: done, left, current keyword, eta) or `get_search` / `list_searches` every 20-60 s.
- Positions are 1-100 within the pages read (`pages`, 10 results a page; 1 by default, so top 10). 0 or null means the domain was not found in those pages. Lower is better; `previous` is the check before, `best` the best seen.
- Country and language default to vn / vi (Google Vietnam in Vietnamese); `locales` lists the others that can be searched.
- Rate limit: 120 calls a minute per key. 429 RATE_LIMITED: wait a few seconds and retry. 402 INSUFFICIENT_CREDITS: stop and tell the user to top up (Nạp tiền in the app; it says how many credits are needed and left). Errors come as {error, code}: error is for people (Vietnamese), code for you.
- Answer the user briefly, in their language, with a short table: keyword | position | change (previous → now) | URL; then the average position and the top 3/10 counts for a project.

## 5. Then
Ask me what to check next: for example "Kiểm tra thứ hạng của shop.vn cho từ khoá 'giày chạy bộ'", or a project to check.