# An SEO MCP server for Claude Code, Cursor and Codex.

URL: https://serpel.app/developers/mcp

Updated: 2026-10-10

An SEO MCP server lets a coding agent read your rankings, search data and audit results as tools instead of copying numbers into a prompt. Serpel’s remote MCP server at `serpel.app/mcp` offers 13 tools and signs you in with OAuth in the browser. Of these, 12 are free and read-only, and the one paid tool runs only within the budget you approve.

## What the Serpel MCP server gives your agent

- **OAuth sign-in:** The agent opens your browser once. You choose the workspace and approve access. No API key goes into a configuration file.
- **Read-only tools:** 12 of 13 tools only read data. Each checks scope, project role and workspace, like the dashboard.
- **A budget for paid tools:** `research_keywords` is the only tool that spends credits, and only within the limits you set.
- **Jobs followed by ID:** Crawls and rank checks start in the dashboard, CLI or API. The agent follows them with `get_job_status`.
- **Code-aware findings:** `get_codebase_overview` connects SEO findings to the routes you uploaded with `serpel scan`.
- **Works with your agent:** Claude Code, Claude Desktop, ChatGPT, Codex, Cursor, VS Code with GitHub Copilot and the Gemini CLI use one URL.

## What is an SEO MCP server?

The Model Context Protocol (MCP) lets AI apps call tools on a server. An SEO MCP server exposes SEO data as tools, so a coding agent can answer “why did this keyword drop?” by reading rankings, crawl issues and search data itself, and then change the code. Serpel’s server is remote, so there is nothing to install: your agent connects to a URL.

The server uses Streamable HTTP and answers each request on its own, with JSON. Lists are capped at 25 rows, so agents get compact answers instead of raw data. For Claude Code SEO work, that is the whole integration: one command adds the server.

## How do you connect Claude Code, Cursor and other agents?

Every client uses the same URL. The first tool call opens a browser window where you sign in, choose the workspace and approve access. The [Claude Code setup guide](https://serpel.app/docs/mcp/claude-code) walks through it step by step.

| Client | How to connect |
| --- | --- |
| Claude Code | Run `claude mcp add --transport http serpel https://serpel.app/mcp`. |
| Claude Desktop and claude.ai | Add a custom connector with the URL under Connectors. |
| Cursor | Add the URL to `.cursor/mcp.json`, as shown above, and sign in when the browser opens. |
| Codex | Add `url = "https://serpel.app/mcp"` under `[mcp_servers.serpel]` in `~/.codex/config.toml`. |
| ChatGPT | In developer mode, add a connector with the URL under Apps and Connectors. |
| VS Code with GitHub Copilot | Add a server of type `http` with the URL to `.vscode/mcp.json`. |
| Gemini CLI | Set `httpUrl` to the URL under `mcpServers` in `~/.gemini/settings.json`. |

## Which tools does the Serpel MCP server offer?

The server offers 13 tools. Each has a title, a description, an input schema and annotations, and the 12 free tools are marked read-only.

| Tool | What it does | Cost |
| --- | --- | --- |
| `list_projects` | Lists the projects you can access, with IDs, domains, markets and your role. Call it first: every other tool needs a project ID. | Free |
| `get_project_overview` | Summarises one project: audit score, rankings, AI visibility, tasks, top issues and next steps. | Free |
| `get_keyword_rankings` | Returns tracked keywords with the latest Google position, the previous position and the change. | Free |
| `get_search_performance` | Returns clicks, impressions, CTR and position from Search Console or Bing, compared with the previous period. | Free |
| `find_keyword_opportunities` | Finds search queries on positions 4 to 20 with impressions and matches them against your tracked keywords. | Free |
| `get_crawl_issues` | Lists the issues of the latest crawl by type, severity and affected pages, with the score and its change. | Free |
| `get_ai_visibility` | Shows how often ChatGPT cites or mentions your website and how often Google AI Overviews cite it, with the latest result per prompt. | Free |
| `get_seo_recommendations` | Lists prioritised recommendations with impact, estimated clicks, effort, page, code route and next action. | Free |
| `get_codebase_overview` | Summarises the latest `serpel scan` snapshot: routes without metadata and differences between code and the live site. | Free |
| `get_conversion_performance` | Shows sessions, conversions and conversion rate per landing page from your analytics. | Free |
| `analyze_competitors` | Compares the project with saved competitors from stored results, including keywords where a competitor leads. | Free |
| `get_job_status` | Returns the status, progress and result of a background job by its ID. | Free |
| `research_keywords` | Looks up keyword ideas or metrics: search volume, CPC, keyword difficulty and intent. Returns at most 25 keywords. | Credits |

Long-running work such as crawls and rank checks never starts inside a tool call. Start it in the dashboard, the [CLI](https://serpel.app/developers/cli) or the [REST API](https://serpel.app/developers/api), and let the agent follow it with `get_job_status`.

## What can you ask an agent with Serpel connected?

- “Which keywords moved since the last rank check?” The agent calls `get_keyword_rankings`.
- “Which queries rank on positions 4 to 20?” It calls `find_keyword_opportunities`.
- “What should I fix first?” It combines `get_crawl_issues` and `get_seo_recommendations`.
- “Which routes in my code lack a title or description?” It calls `get_codebase_overview`.

## How do budget rules protect your credits?

Only `research_keywords` spends credits. It runs only when every condition holds:

1. The connection includes the `keywords:write` permission. OAuth sign-in grants it.
2. The workspace has an active Starter or Pro plan.
3. The workspace owner has switched on “Agents can spend credits” in the Billing settings, or ran `serpel agents allow`.
4. The call costs at most 50 credits, and today’s agent spending plus the call stays under the daily limit. The default limit is 500 credits, and you can set it up to 100,000. The day follows UTC.
5. The balance covers the call. Credits come from your monthly plan allowance first, then from credits you bought.

A repeated call with the same `requestId` is charged once. If a rule blocks the call, the tool returns a specific error such as `plan_required`, `agent_spend_disabled`, `daily_cap_reached` or `insufficient_credits`. Plans and credit prices are on the [pricing](https://serpel.app/pricing) page.

## Is it safe to give an agent access?

- OAuth access tokens work only at the MCP server. The REST API rejects them.
- Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use.
- Tools respect token scopes, your project role and your workspace. A project you can’t access returns `not_found`.
- You can disconnect an app at any time under Settings, API, Connected apps. Disconnecting revokes its access.

## Connect in three steps

1. **Add the server** Point your agent at the Serpel URL. For Claude Code, one command does it.

```bash
claude mcp add --transport http serpel https://serpel.app/mcp
```

2. **Sign in** The first tool call opens the browser. Choose the workspace, check the permissions and approve.

3. **Ask a question** Start with “List my Serpel projects”, or ask why a keyword dropped. The agent calls `list_projects` first, because every other tool needs a project ID.

## Frequently asked questions

### Does Serpel’s MCP server work with Claude Code?

Yes. Run `claude mcp add --transport http serpel https://serpel.app/mcp`, then sign in when the browser opens. Cursor, Codex, VS Code with GitHub Copilot, ChatGPT and the Gemini CLI connect to the same URL.

### Can the agent start a crawl or a rank check?

No. The MCP server doesn’t start long-running jobs. Start crawls and rank checks in the dashboard, the CLI or the API. The agent can follow progress with `get_job_status` and read the results as soon as the job has succeeded.

### Can an agent spend my credits?

Only through `research_keywords`, and only if you have a Starter or Pro plan, have switched on “Agents can spend credits” and stay within the per-call and daily limits. Every other tool is free.

### Do I need an API key for the MCP server?

No. Sign in with OAuth in the browser. A client without OAuth support can use an API token with the `mcp:read` permission instead, plus the read permissions for the data you want to use, and send it as a bearer token.