Connect Claude Code to Serpel over MCP

How do you add the Serpel MCP server to Claude Code?

1. 1

   Add the server.

   Run this command in your terminal. serpel is the name you give the server, and --transport http selects the remote HTTP transport.

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

2. 2

   Sign in.

   Start Claude Code and run /mcp. Select serpel and follow the steps in your browser: sign in to Serpel, choose the workspace and allow access. If the browser does not open, copy the address that Claude Code shows. You can also start the sign-in from the shell with claude mcp login serpel.

   /mcp

3. 3

   Check the connection.

   claude mcp list shows the status of every server. Serpel should read as connected. Then ask Claude Code a question about your site.

   claude mcp list
   claude mcp get serpel

Choose the scope of the server

By default, Claude Code stores the server for the current project and only for you. --scope changes that.

With --scope project, the entry in .mcp.json looks like this.

{
  "mcpServers": {
    "serpel": {
      "type": "http",
      "url": "https://serpel.app/mcp"
    }
  }
}

The file contains no secret. Every teammate signs in with their own Serpel account and sees only their own projects.

How does the OAuth sign-in work?

Claude Code follows the MCP authorisation specification: OAuth 2.1 with PKCE (S256). The server answers an unauthenticated request with HTTP 401 and a WWW-Authenticate header that points to the discovery documents. The client registers itself, opens /oauth/authorize in your browser and exchanges the code at /oauth/token. You do not need to create a client ID or a secret.

On the consent page you sign in to Serpel if needed, choose the workspace and review the permissions. The access token gets these scopes: mcp:read, projects:read, rankings:read, audit:read, keywords:read, keywords:write, recommendations:read, codebase:read. It only works at the MCP server. The REST API rejects it. Access tokens last 1 hour. Refresh tokens last 30 days and rotate each time they are used, so you stay signed in without doing anything.

To disconnect an app, open Settings, API, Connected apps in the dashboard. Disconnecting revokes the access and refresh tokens at once.

How do you connect with an API token instead?

Use an API token when Claude Code cannot open a browser, for example on a server or in CI. Create the token in the dashboard under Settings, API tokens. It needs the mcp:read scope, plus the scopes of the tools you want to use:

• mcp:read: required for every call. Without it, the server answers with HTTP 403.
• projects:read: list_projects, get_project_overview, get_search_performance, find_keyword_opportunities, get_conversion_performance.
• rankings:read: get_keyword_rankings, get_ai_visibility, analyze_competitors, and get_job_status for rank checks, AI checks and monitoring runs.
• audit:read: get_crawl_issues, and get_job_status for crawls.
• recommendations:read: get_seo_recommendations.
• codebase:read: get_codebase_overview.
• keywords:write: research_keywords.

You can restrict the token to single projects. The tools then see only those projects.

Put the token in an environment variable and reference it in .mcp.json. Claude Code expands ${SERPEL_TOKEN} from your environment, so the token never lands in the file.

{
  "mcpServers": {
    "serpel": {
      "type": "http",
      "url": "https://serpel.app/mcp",
      "headers": {
        "Authorization": "Bearer ${SERPEL_TOKEN}"
      }
    }
  }
}

You can also pass the header on the command line with --header. The shell expands the variable when you run the command, and Claude Code stores the resulting token in its own configuration file, so prefer the .mcp.json variant.

claude mcp add --transport http serpel https://serpel.app/mcp --header "Authorization: Bearer $SERPEL_TOKEN"

Which tools does the Serpel MCP server provide?

The server offers 13 tools. All of them check the scope, your project role and your workspace before they return data, so an agent only sees what you could see yourself. Lists hold at most 25 rows, and every result is compact JSON with a short summary sentence.

All tools except research_keywords are read-only and free. They never change your data or your website. Crawls, rank checks, AI visibility checks and monitoring runs do not start inside a tool call. You start them in the dashboard, with the CLI or through the REST API, and then follow them with get_job_status. Tools that need a data source, such as Search Console, tell the agent what to connect in the dashboard when it is missing.

In apps that can show interactive cards, such as ChatGPT and Claude, get_keyword_rankings, get_crawl_issues, find_keyword_opportunities and get_ai_visibility also show their result as a card. Every other client gets the same data as text. ChatGPT does not offer research_keywords.

How do agent spending and budgets work?

research_keywords is the only tool that uses credits, and it runs only when every one of these conditions holds. Serpel checks them in this order:

1. The token has the keywords:write scope. OAuth sign-in grants it.
2. The workspace has an active Starter or Pro plan.
3. The workspace owner allowed agent spending: “Agents can spend credits” under Settings, Billing, Agents and AI apps, or serpel agents allow.
4. One call costs at most 50 credits, and today’s agent spending plus the call stays within the daily limit. The default limit is 500 credits per day. You can set it between 1 and 100,000 with serpel agents daily-limit <credits>. The day follows UTC and resets at 00:00 UTC.
5. The workspace has enough credits. Serpel uses the monthly plan allowance first and then credits you bought.

A research for 25 keyword ideas costs 12 credits, and a research of the keywords a domain ranks for costs 6 credits. Fewer results cost fewer credits. Every result states the credits charged (credits.charged), your balance, the remaining monthly allowance and the remaining agent budget for the day (dailyAgentBudget). If the agent repeats a call after a network error, it passes the same requestId, and the research is charged once.

Tool results only link to the dashboard and to the pricing page. They never link to a checkout or a top-up, so an agent cannot buy credits for you.

Which prompts work well in Claude Code?

Ask in plain language. Claude Code picks the tools and starts with list_projects to find the project ID.

• “List my Serpel projects and show the audit score of the one for example.com.”
• “Which tracked keywords lost the most positions since the last rank check? Check the latest crawl issues for the pages that dropped.”
• “Find queries on positions 4 to 20 for my project and tell me which page in this repository I should improve first.”
• “Show the open Serpel recommendations and fix the one with the highest impact in the code.”
• “Compare my rankings with my competitors and list the keywords where a competitor is ahead.”
• “Research keyword ideas for ‘cold brew concentrate’ in the US. Tell me what it costs before you run it.”

For prompts that connect SEO findings to your source files, upload a snapshot of your routes first with serpel scan --project <id>. get_codebase_overview and get_seo_recommendations use it. The CLI reference explains the scan.

Is there a Serpel plugin for Claude Code?

Serpel has a plugin package with a skill that tells the agent which tool to use for which question. It is not published to any plugin marketplace yet, so the claude mcp add command above is the supported way to connect. This page will change when the plugin is published.

How do you troubleshoot the connection?

Run /mcp in Claude Code to see the status of the server, and claude mcp list in the shell. Removing the server with claude mcp remove serpel also deletes its stored OAuth tokens, so you can start the sign-in again from scratch. In /mcp, “Clear authentication” revokes the stored access.

More about claude mcp and the configuration scopes is in the Claude Code MCP documentation.