All docs pages

MCP server.

Ask an AI assistant about your rankings, traffic and alerts. The assistant reads your Serplyze data through the Model Context Protocol (MCP); it can't change anything.

01 — Server

One URL for every assistant

The server lives at https://serplyze.com/mcp (Streamable HTTP). It has twelve read-only tools. Every number comes from the same code as the REST API and the app, with the same date rules and limits.

Sign in (OAuth)Add the URL as a custom connector. The assistant opens a Serplyze page where you sign in, pick the workspace and approve read-only access. Best for Claude, ChatGPT and VS Code.

API keySend a workspace API key as Authorization: Bearer ord_live_…. Best for Cursor, Claude Code and scripts. Make one in Settings → API and Sheets.

Plan

The MCP server is part of the paid plans, like the API. On Free, the tools answer with a message that the workspace needs a paid plan.

02 — Setup

Claude and Claude Desktop

In Claude, open Settings → Connectors and choose Add custom connector.
Name it Serplyze and paste https://serplyze.com/mcp as the URL. Leave the OAuth fields empty.
Select Connect. Sign in to Serplyze if asked, pick the workspace and select Approve.
In a chat, turn the Serplyze connector on and ask, for example: "Which keywords lost the most positions this week on example.com?"

Claude Desktop uses the same connectors. To use an API key in Claude Desktop instead, add Serplyze to claude_desktop_config.json through the mcp-remote bridge (needs Node.js):

claude_desktop_config.json

{
  "mcpServers": {
    "serplyze": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://serplyze.com/mcp", "--header", "Authorization:${SERPLYZE_AUTH}"],
      "env": { "SERPLYZE_AUTH": "Bearer ord_live_your_key" }
    }
  }
}

03 — Setup

Claude Code

With an API key:

bash

claude mcp add --transport http serplyze https://serplyze.com/mcp \
  --header "Authorization: Bearer ord_live_your_key"

Or without a key: add the server, then run /mcp in Claude Code and choose Authenticate to sign in and approve in the browser.

bash

claude mcp add --transport http serplyze https://serplyze.com/mcp

04 — Setup

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project) and keep the key in an environment variable:

~/.cursor/mcp.json

{
  "mcpServers": {
    "serplyze": {
      "url": "https://serplyze.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SERPLYZE_API_KEY}" }
    }
  }
}

Limit

Sign-in (OAuth) only returns to https addresses and to localhost. Clients that use their own link scheme for the return trip, such as Cursor's cursor://, can't use it: give them an API key.

05 — Setup

ChatGPT

In ChatGPT, open Settings → Apps & Connectors. Under Advanced settings, turn on Developer mode (your ChatGPT plan must offer it).
Choose Create, name it Serplyze, paste https://serplyze.com/mcp as the MCP server URL and pick OAuth as the authentication.
Sign in to Serplyze, pick the workspace and select Approve. Then turn the connector on in a chat.

06 — Setup

VS Code and other clients

Any MCP client that speaks Streamable HTTP works. VS Code, in .vscode/mcp.json:

.vscode/mcp.json

{
  "servers": {
    "serplyze": { "type": "http", "url": "https://serplyze.com/mcp" }
  }
}

Clients find the sign-in on their own: /mcp answers 401 with a WWW-Authenticate header that points to /.well-known/oauth-protected-resource/mcp, which names Serplyze as the authorization server (/.well-known/oauth-authorization-server). Clients register themselves (dynamic client registration) and use the authorization code flow with PKCE.

07 — Tools

Twelve tools

Tool	What it returns
`list_projects`	Your projects with ids, sync state, data range, tracked keywords and the Dashboard figures: visibility of the last 7 final days, keywords in the top 10, clicks and impressions of the last 28 days, open alerts.
`get_site_performance`	Whole-property clicks, impressions, CTR and position for a range, the change against the previous period, a year earlier or a custom range, and the daily series. By device or country.
`list_groups`	Keyword groups and folders with the summed metrics of their keywords.
`get_keywords`	Tracked keywords with position, clicks, impressions and CTR and their change against the comparison. Filter by group or text, sort, page.
`get_keyword_history`	One keyword's daily position, clicks and impressions.
`get_top_movers`	Biggest gains and losses, new and lost keywords, with the rank tracker's mover rules.
`get_queries`, `get_pages`	Every Search Console query or page of the range, most clicks first, paginated (the Traffic lists).
`get_breakdowns`	Countries, devices, search appearances and brand vs non-brand.
`get_alerts`	Open or resolved alerts with the app's text.
`get_notes`	Chart notes (releases, migrations, campaigns) to explain changes.
`get_ai_search_impact`	The AI search screen's estimate of clicks and impressions from AI-style searches and their share.

Every tool takes the project id from list_projects (or the project's domain) and dates as YYYY-MM-DD: from and to, or period such as 28d or 3m. The default is the 28 days up to the last synced day; a range is at most 486 days. Keyword data starts where the plan's keyword history starts.
Comparisons default to the previous period of the same length. positionChange above 0 means the keyword moved up.
ctr is a ratio from 0 to 1. Lists come as columns and rows to keep answers short; limit and offset page through them.
Days after provisionalAfter are still being revised by Google.

08 — Access

What a connection can see

Read-only: No tool writes. There is no tool for billing, team members, connections or settings.
Sign-in connections read as you: An app you approve sees the projects you can see in the workspace you picked, nothing more. A client of an agency sees only the projects shared with them, without alerts or AI search, as in the client portal. If you leave the workspace or are removed from it, the connection stops working.
API keys read the whole workspace: Like the REST API, a key reads every project of its workspace. Only owners and admins can make keys.
Limits: 120 requests a minute per key or connection (shared with the REST API for a key), of which at most 20 a minute for the list tools (get_keywords, get_top_movers, get_queries, get_pages). One request carries one call: batches are refused. Lists that aren't cached yet can take up to a minute.

Disconnect an app

Settings → API and Sheets → Connected apps lists every app connected by sign-in, with when it was connected and last used. Revoke stops it at once. Members see their own apps; owners and admins see and can revoke every app connected to the workspace. Clients find their apps on the portal dashboard. Resetting your password or signing out everywhere (or all other devices) disconnects every app too. Approving, denying and revoking are written to the audit log.

Tokens

A sign-in gives the app an access token valid for one hour and a refresh token valid for 30 days, renewed with each use. Serplyze stores only hashes of them. A refresh token used twice ends the connection, in case it was copied.