In short
- Serpkin's MCP server has 28 tools and 5 prompts; this list is generated from its contract.
- The loop: serpkin_next_mission, implement, serpkin_submit_result, then serpkin_verify_mission on the preview and in production.
- Reading is free. Research tools that cost credits say so, and the agent asks you before spending them.
- At a plan limit, the error carries an upgrade note that the agent mentions once, with the link.
Serpkin is an MCP server with 28 tools and 5 prompts. Your coding agent calls them; you rarely need to name them yourself. This page lists every tool from the server's own contract, grouped by job, with what it does, its main inputs and what it costs. Inputs marked with * are required. Every call also takes a project_id.
How the agent uses them
The server tells every agent the same loop when it connects:
- 1serpkin_
next_ missionGet the one mission worth doing now, with files and steps. - 2ImplementEdit the listed files, adapt the snippets, run your tests.
- 3serpkin_
submit_ resultRecord the pull request, commit and preview URL. - 4serpkin_
verify_ missionCheck the preview, then production after a person deploys.
Read tools are free. Research tools that cost credits say so, and the server tells the agent to state the cost and ask you first. If a mission isn't relevant or is already done, the agent dismisses it with serpkin_update_mission and a reason.
Find and ship the work
Pick the next mission, read it, record the change and verify it.
| Tool | What it does | Main inputs | Credits |
|---|---|---|---|
serpkin_ | The single most useful open mission, with why now, the files to change, a step-by-step plan and the checks that prove it's done. | site_id* | Free |
serpkin_ | Queue a technical scan that creates foundation missions. | site_id*, idempotency_key* | Free |
serpkin_ | The ranked list of missions for a site, filterable by status and category. | site_id*, status, category, limit, cursor | Free |
serpkin_ | A full mission by id: rationale, targets, source files, recipe, implementation plan and acceptance criteria. | mission_id* | Free |
serpkin_ | Turn a saved opportunity into a mission, without duplicates. | site_id*, opportunity_id*, category*, idempotency_key* | Free |
serpkin_ | The site's business, market, framework, ownership and health from the latest full scan. | site_id* | Free |
serpkin_ | Record what was shipped: pull request, commit, preview URL and test summary. | mission_id*, artifacts*, notes, idempotency_key* | Free |
serpkin_ | Check a submitted mission on the preview, in production, or against evidence for content work. | mission_id*, environment*, preview_url, idempotency_key* | Free |
serpkin_ | Start, dismiss or restore a mission. Dismissing takes a reason and an optional note. | mission_id*, action*, reason, note, idempotency_key* | Free |
Measure and watch
Search performance, rankings, results, backlinks, AI visibility and site health. Reading is free.
| Tool | What it does | Main inputs | Credits |
|---|---|---|---|
serpkin_ | Daily clicks, impressions, CTR and position, with mission markers and top queries. | site_id*, period, country, language, limit, cursor, … | Free |
serpkin_ | Get, add, remove or replace the site's tracked keywords. | site_id*, action*, keyword_ids, country, language, idempotency_key, … | Free |
serpkin_ | The last 28 days of Search Console data against the 28 days before. | site_id*, period*, comparison_period*, country*, language* | Free |
serpkin_ | A mission's events in order: lifecycle, implementation, verification and results. | site_id*, mission_id, limit, cursor | Free |
serpkin_ | Measured results of shipped missions at the baseline, 14 and 28 days. | site_id*, mission_id, limit, cursor | Free |
serpkin_ | Whether Google shows an AI Overview for your important queries and whether it cites you. | site_id*, refresh, queries, idempotency_key | Free to read; 1 per query to check now |
serpkin_ | Tracked keyword positions, 7-day changes, ranking URLs and suggested keywords. | site_id* | Free |
serpkin_ | Referring domains, new and lost links, links to broken pages and the link gap. | site_id*, refresh, idempotency_key | Free to read; 5 per refresh |
serpkin_ | Is my site OK? The scheduled check's open alerts and recent wins. | site_id* | Free |
serpkin_ | The Monday "Your SEO week" summary as data, per site. | site_id | Free |
Research
Keywords, results pages, competitors and content briefs. Some of these spend credits.
| Tool | What it does | Main inputs | Credits |
|---|---|---|---|
serpkin_ | Keyword ideas with volume, difficulty and intent for a seed phrase. | site_id, query*, country*, language*, limit, cursor, … | 2 per seed |
serpkin_ | Group saved keywords into topics, with page matches and overlap warnings. | site_id, keyword_ids*, country*, language*, idempotency_key* | Free |
serpkin_ | The current top results for up to 3 keywords. | keywords*, country*, language*, limit, cursor, idempotency_key* | 1 per keyword |
serpkin_ | The site's organic search competitors in a market. | site_id*, domains, country*, language*, limit, cursor, … | 3 per request |
serpkin_ | Keywords competitors rank for that the site doesn't. | site_id*, competitor_ids*, country*, language*, limit, cursor, … | 3 per competitor |
serpkin_ | Starting briefs from saved keyword or clustering reports. | site_id*, research_report_ids*, country*, language*, idempotency_key* | Free |
serpkin_ | A brief from the top results: outline, questions people ask, length, terms and internal links. | mission_id, site_id, query, refresh, idempotency_key | Free to read; 2 to build one |
Set up
Register a site and follow background jobs.
| Tool | What it does | Main inputs | Credits |
|---|---|---|---|
serpkin_ | Register a website and get its ownership options. | origin*, business_description*, audience*, framework, country*, language*, … | Free |
serpkin_ | Poll or cancel a background job such as a scan, research or verification. | job_id*, action*, idempotency_key | Free |
Prompts
Prompts are ready-made requests your agent can run, for clients without the Claude Code plugin. They follow the same rules as the tools.
| Prompt | Title | What it does |
|---|---|---|
next_ | Do the next SEO mission | Get the highest-priority SEO mission and implement it in this repository. |
ship_ | Ship a mission | Record the implementation, check the preview and verify the mission. |
check_ | Check a preview for SEO regressions | Compare a preview deployment with production (free). |
seo_ | How is my site doing? | This week's SEO summary: clicks, rankings, wins, anything broken and the next mission (free). |
research_ | Research a topic | Keyword ideas for a topic, grouped into page ideas that fit this site (2 credits). |
Limits and upgrade notes
When a call reaches a plan limit, for example the monthly missions or credits, the error includes an upgrade object: which limit was reached, your usage, what the next plan includes and a link to your plan settings. serpkin_next_mission and serpkin_weekly_summary also include it when a limit is close. The server tells the agent to mention it to you once, with the link, and never to push or repeat it.
Connect a client
npx serpkin configures Claude Code, Cursor and Codex for you. Any other MCP client can connect to the HTTP endpoint with your agent key as a bearer token:
{
"mcpServers": {
"serpkin": {
"type": "http",
"url": "https://serpkin.com/api/mcp",
"headers": { "Authorization": "Bearer ${SERPKIN_API_KEY}" }
}
}
}The key comes from npx serpkin or Settings → Agent setup, and is read from the SERPKIN_API_KEY environment variable, so it never sits in the repository. Setup per agent: Claude Code, Cursor and Codex.