Get started
Serpel developer documentation
Serpel has three developer interfaces that share one account, one set of permissions and one credit balance: the serpel command line, a REST API and a remote MCP server for coding agents. This documentation shows how to sign in, what each interface can do and how to set it up. All three work on the same projects as the dashboard.
What can you do with the Serpel CLI, API and MCP server?
Every interface reads and changes the same rankings, crawls, keyword lists and tasks as the dashboard. Pick the one that fits where you work.
| Interface | Use it to | Sign in with | Documentation |
|---|---|---|---|
| CLI | Run crawls, rank checks and exports from a terminal, a script or a CI job. | Browser approval (serpel auth login) or an API token in SERPEL_TOKEN. | CLI reference |
| REST API | Build your own integrations that read or change the data the dashboard shows. | An API token in the Authorization header. | REST API |
| MCP server | Let Claude Code, Cursor or Codex read your SEO data while they work on your code. | OAuth in the browser, or an API token with the mcp:read scope. | Claude Code, Cursor, Codex |
How do you authenticate with Serpel?
Serpel knows two kinds of credentials. API tokens serve the CLI and the REST API. OAuth access tokens serve MCP clients and work nowhere else.
API tokens
An API token starts with vsk_ and is shown exactly once when you create it. Each token has a name, a list of permissions called scopes, an optional restriction to single projects and an optional expiry of 1 to 365 days. Create tokens in the dashboard under Settings, API tokens, with serpel tokens create or with POST https://serpel.app/api/v1/tokens. Send the token as Authorization: Bearer vsk_….
Browser approval for the CLI
serpel auth login starts a device login. The CLI prints a code and opens the dashboard, you check the code and choose the permissions, and the CLI stores the token it receives. Nothing to copy and paste. The CLI reference explains the flow and the other ways to sign in.
OAuth for MCP clients
MCP clients such as Claude Code, Cursor and Codex sign in with OAuth 2.1 and PKCE. The client registers itself, you approve it on a consent page in the browser and choose the workspace. Access tokens last 1 hour and refresh tokens 30 days. The REST API rejects OAuth tokens with HTTP 403. You can disconnect any app under Settings, API, Connected apps.
What are the base URLs?
| Interface | Address | Notes |
|---|---|---|
| REST API | https://serpel.app/api/v1 | JSON over HTTPS. GET /api/v1 returns an index of all endpoints without authentication. |
| MCP server | https://serpel.app/mcp | Streamable HTTP, POST only, JSON responses. |
| Health check | https://serpel.app/api/health | Returns ok and the database status without authentication. |
| CLI | https://serpel.app | The default API address of the CLI. Override it with --api-url or SERPEL_API_URL. |
curl https://serpel.app/api/v1/projects \
-H "Authorization: Bearer $SERPEL_TOKEN"How do credits work for CLI, API and MCP calls?
Reading data is free. Operations that query a data provider use credits, at the same prices as in the dashboard. New accounts start with 100 welcome credits.
| Operation | Unit | Credits |
|---|---|---|
| Scheduled monitoring, up to top 50 | per keyword | 2 |
| Scheduled monitoring, top 100 | per keyword | 3 |
| Rank check right now, up to top 50 | per keyword | 5 |
| Rank check right now, top 100 | per keyword | 9 |
| ChatGPT answer check | per question | 2 |
| Google AI Overview check | per question | 2 |
| Keyword research | per search | 8 + 4 per 50 results |
| Keyword research by domain | per domain | 4 + 2 per 50 results |
| Site crawl | per 20 pages | 1 |
Check a price before you run an operation with serpel billing estimate or POST /billing/estimate. An estimate books nothing. If the balance is too low, the API answers with HTTP 402 and the error code insufficient_credits, and the CLI exits with code 6.
Coding agents get an extra safeguard. The MCP tool research_keywords is the only tool that uses credits, and it only runs when you allow agents to spend credits and stay within a daily limit. The Claude Code guide lists the rules.
Where should you start?
- CLI reference: install the CLI, sign in, run every command group and use it in CI.
- REST API: authentication, scopes, errors, rate limits, the endpoint list and curl examples.
- Claude Code: one command to connect, the tool list and the agent spending rules.
- Cursor: the
mcp.jsonentry for a remote server with OAuth. - Codex:
codex mcp addorconfig.toml, thencodex mcp login.
Updated 10 Oct 2026
See also
- CLIThe Serpel SEO CLI runs rank checks, site audits and AI visibility checks from your terminal, with JSON output, documented exit codes and CI support.
- SEO APISerpel’s SEO API is a REST API for rank tracking, site audits, AI visibility and search data, with bearer tokens, JSON responses and credit-based pricing.
- MCP serverSerpel’s SEO MCP server gives Claude Code, Cursor and other agents your rankings, audits and search data, with OAuth and a budget for paid tools.
- Serpel CLI referenceReference for the serpel command line: install, sign-in, every command group, JSON output, exit codes and a GitHub Actions example.