# Serpel developer documentation

URL: https://serpel.app/docs

Updated: 2026-10-10

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](https://serpel.app/docs/cli) |
| REST API | Build your own integrations that read or change the data the dashboard shows. | An API token in the `Authorization` header. | [REST API](https://serpel.app/docs/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](https://serpel.app/docs/mcp/claude-code), [Cursor](https://serpel.app/docs/mcp/cursor), [Codex](https://serpel.app/docs/mcp/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](https://serpel.app/docs/cli) 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.

> **Give tokens the least access they need:** A token only works with the scopes you chose, and a token restricted to projects cannot see any other project (the API answers with 404 for those). Create one token per script or CI job, with only the scopes it needs. The 18 available scopes are listed in the [REST API reference](https://serpel.app/docs/api).

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

```bash
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](https://serpel.app/docs/mcp/claude-code) lists the rules.

## Where should you start?

- [CLI reference](https://serpel.app/docs/cli): install the CLI, sign in, run every command group and use it in CI.
- [REST API](https://serpel.app/docs/api): authentication, scopes, errors, rate limits, the endpoint list and curl examples.
- [Claude Code](https://serpel.app/docs/mcp/claude-code): one command to connect, the tool list and the agent spending rules.
- [Cursor](https://serpel.app/docs/mcp/cursor): the `mcp.json` entry for a remote server with OAuth.
- [Codex](https://serpel.app/docs/mcp/codex): `codex mcp add` or `config.toml`, then `codex mcp login`.