# MCP access

SERPclimber exposes an OAuth-protected Model Context Protocol server at this exact URL:

```text
https://serpclimber.com/mcp
```

In SERPclimber, use the **MCP** menu and choose **Copy MCP server URL**, or open **Settings → Account → MCP access**. Paste the URL into a client that supports remote Streamable HTTP MCP servers. The client opens SERPclimber so you can sign in and approve access.

Opening the URL as a normal web page is not an MCP connection test. Browser visits redirect to this guide. An MCP client sends protocol requests with `POST`; before authorization, a `401` response that points to SERPclimber's protected-resource metadata is the expected healthy response. Use the production URL for phone and hosted clients. `http://localhost:3000/mcp` works only while the local app is running and only for a client that can reach that machine.

## Connect a client

There is nothing to install and no API key to paste. Every client authenticates the same way: it discovers the OAuth endpoints from the server URL, opens SERPclimber in a browser, and you approve the scopes it asked for.

**Claude Code**

```bash
claude mcp add --transport http serpclimber https://serpclimber.com/mcp
```

**Claude Desktop, claude.ai, and ChatGPT** — add a custom connector and give it the server URL. In ChatGPT this is **Settings → Connectors → Add**.

**Cursor, VS Code, and other `mcp.json` clients** — one entry:

```json
{
  "mcpServers": {
    "serpclimber": { "url": "https://serpclimber.com/mcp" }
  }
}
```

If a client asks for a transport, choose Streamable HTTP. SSE and stdio are not offered.

## Scopes

- `mcp` reads workspace data: active projects, integration status, billing and project access, Search Console, Pages, saved AI Visibility evidence, crawler activity, experiments, settings, and documentation.
- `mcp:write` also permits paid live services and the two-step action workflow. It does not let a client bypass project ownership, subscription, usage, integration, or workflow checks.

SERPclimber asks compatible clients for both scopes during the normal connection flow so the agent can use the complete tool set after you approve it. A client may explicitly request only `mcp` for a read-only connection; the consent screen always shows the scopes that specific client requested.

Approving OAuth does not require a paid plan. If a tool needs a subscription, writable project, connected integration, or remaining usage, that individual call returns a readable error such as `subscription-required`, `project-read-only`, or `usage-limit-reached`. The OAuth connection remains valid.

## Writes require two steps

MCP clients cannot send a direct mutation. They first call `actions_prepare`. SERPclimber freezes the targets, preconditions, warnings, reversibility, and expiry into a short-lived plan. The client then calls `actions_execute` with only that plan ID.

Plans are one-time, expire, and are checked again before execution. MCP v1 supports Page refresh/rank/eligibility changes, the Experiment and Draft lifecycle, keyword updates, project feature/settings changes, and workspace defaults. It does not support creating, renaming, changing the domain of, archiving, or changing the default Project, and it cannot bind integrations.

Discard removes unpublished work. Running and completed Experiments retain their evidence and use the normal end or decision workflow.

## Tool catalog

MCP clients receive each tool's current input schema and description through `tools/list`. This catalog explains which tool to choose. All standard tools require `mcp`; rows marked `mcp:write` additionally require that scope. Successful reads return the complete sanitized result in both MCP `structuredContent` and text content, so clients that do not expose structured results still receive rows, IDs, positions, deltas, question text, citations, and dossier details. Tool results never include credentials, encrypted fields, raw OAuth tokens, or platform-provider capacity.

Start a Project-specific task with `workspace_read_context`, copy the exact `projectId` from its result, and pass that ID to later tools. An explicit Project ID, name, or domain that does not match an active owned Project returns a selection error; SERPclimber never silently substitutes the default Project. For GSC tools, passing `projectId` also selects that Project's bound Search Console property. Page rows include `hostname` so domain properties spanning `www`, app, and other subdomains can be separated.

For common choices:

- Use `search_console_analyze` for flexible or site-wide GSC questions, `pages_read_search_console_inventory` for the exact Pages table, and `pages_list_project_inventory` for product discovery and Experiment status.
- Use `pages_rank_experiment_opportunities` to choose the next Page, `pages_read_experiment_opportunity` to inspect one candidate, and `pages_diagnose` for a complete historical dossier.
- Use `ai_visibility_read` with `section: "questions"` to list saved question text, then call it again with `questionId` for stored answers and citations. This is a free read; use `ai_visibility_ask_engines` only when a fresh metered request is intended.
- Use `projects_prioritize_work` for broad priorities, not for choosing the next Experiment Page.

### Workspace and documentation tools

| Tool | Access | What it does and when to use it |
|---|---|---|
| `workspace_read_context` | `mcp` | Lists active Projects with their exact IDs, domains, the default Project, and safe connection summaries. Use its `projectId` before any Project-specific call. |
| `workspace_read_billing` | `mcp` | Reads subscription state, Project capacity, overage settings, usage, and per-Project access. Use to explain billing or read-only blockers. |
| `integrations_read_status` | `mcp` | Reports Google, Wix, and Cloudflare health, defaults, Project bindings, setup routes, and enabled or blocked features. It separately identifies SERPclimber-managed dependencies. |
| `projects_read_overviews` | `mcp` | Returns every active Project with compact Search Console, AI Visibility, and crawler summaries. Use for an all-Projects dashboard; each lens can fail independently. |
| `docs_search` | `mcp` | Searches shipped documentation by product intent and section. Use to locate the right guide before reading it. |
| `docs_read` | `mcp` | Reads one shipped documentation page or named section. Use for detailed product workflow, setup, and permission guidance, not mutable account state. |

### Search Console, Pages, and prioritization tools

| Tool | Access | What it does and when to use it |
|---|---|---|
| `search_console_analyze` | `mcp` | Returns actual first-party GSC rows across queries, Pages, dates, countries, devices, and search appearance, including clicks, impressions, CTR, position, comparison values, and deltas. Pass `projectId` to infer the bound property; Page rows also identify their hostname. |
| `search_console_find_page_movement` | `mcp` | Returns the strongest growing or breakout Page rows against an equal preceding period, including hostname, position, and metric deltas. Pass `projectId` to infer the bound property. Use `search_console_analyze` for declines or arbitrary comparisons. |
| `pages_list_project_inventory` | `mcp` | Lists authoritative discovered Pages by product status, including Opportunities, active workflows, exclusions, and freshness. Use to reproduce the project discovery inventory. |
| `pages_read_search_console_inventory` | `mcp` | Reads the exact paginated Pages table contract: filters, sorting, GSC insights and markers, findings, GA4 revenue/conversions, and freshness. Use when matching the shipped Pages UI. |
| `pages_read_detail` | `mcp` | Reads one Page's stored state, GSC trend and keywords, findings, GA4 impact, saved AI Visibility evidence, and crawler activity. Use for the Page Detail view or selected sections. |
| `pages_rank_experiment_opportunities` | `mcp` | Ranks currently actionable Pages for the next Experiment after eligibility, freshness, path, exclusion, Draft, job, and active-test checks. Use for “what should we test next?” |
| `pages_read_experiment_opportunity` | `mcp` | Inspects one Opportunity's eligibility, warnings, active Experiments, Draft blockers, and generation state. Use after selecting a candidate Page. |
| `pages_diagnose` | `mcp` | Returns a complete Page dossier, not only a count: discovery, GSC, ranks, Experiment history, edits, keyword decisions, eligibility, and audit entries. Use to explain performance or history. |
| `pages_explain_experiment_eligibility` | `mcp` | Explains why a Page was selected, excluded, or blocked using effective rules, score components, overrides, and provenance. Use for eligibility questions, not mutation. |
| `projects_prioritize_work` | `mcp` | Builds a broad operating brief from blockers, Opportunities, Drafts, Experiments, decisions, failures, capacity, and jobs. Use for project priorities or operational health. |

### AI Visibility tools

| Tool | Access | What it does and when to use it |
|---|---|---|
| `ai_visibility_read` | `mcp` | Reads saved overview, paginated question text, full saved answers and cited URLs by `questionId`, competitor citation rows, robots/llms state, and crawler traffic through `overview`, `questions`, `competitors`, or `access` sections. Read stored evidence here without consuming live-ask quota. |
| `ai_visibility_ask_engines` | `mcp:write` | Sends one exact question to selected AI engines and saves the snapshots. Use only for an explicit fresh live ask; subscription and usage checks still apply. |

### Experiment, Draft, and settings tools

| Tool | Access | What it does and when to use it |
|---|---|---|
| `experiments_list` | `mcp` | Lists actual Draft, running, awaiting-decision, and completed Experiments for one Project or an explicit cross-Project report. |
| `experiments_read` | `mcp` | Reads one live Experiment and its Page evidence. Use for the state and results of a specific test. |
| `experiments_analyze_page_keywords` | `mcp` | Analyzes one Experiment Page's keyword ranks, clicks, impressions, CTR, and position. Use for focused keyword evidence. |
| `experiments_review_draft` | `mcp` | Reads one unpublished Draft and returns references for its Draft card and content diff. Use for review, not editing or publishing. |
| `experiments_read_draft_edit_context` | `mcp` | Returns the persisted Draft outline, stable edit target IDs, allowed operations, and `draftRevision`. Use before preparing a safe Draft edit. |
| `settings_read_project` | `mcp` | Reads stored and effective Project or Autopilot settings with inheritance and source provenance. Use to explain which value actually applies. |
| `settings_read_workspace_defaults` | `mcp` | Reads raw Workspace defaults. Use for global inherited policy rather than a particular Project's effective value. |

### Action tools

| Tool | Access | What it does and when to use it |
|---|---|---|
| `actions_prepare` | `mcp:write` | Validates a supported mutation and freezes targets, preconditions, warnings, reversibility, and expiry into a one-time plan. This call does not execute the change. |
| `actions_execute` | `mcp:write` | Executes one pending plan using only its `planId`, after ownership and preconditions are checked again. Plans cannot be executed twice. |
| `actions_retry_failed` | `mcp:write` | Creates a fresh plan containing only failed items from a failed or partial prior plan. Execute the returned plan with `actions_execute`. |

`actions_prepare` accepts these v1 action values:

- Pages: `refresh_pages`, `refresh_page_ranks`, `update_page_keywords`, `exclude_pages_from_experiments`, and `restore_pages_to_experiments`.
- Experiment and Draft lifecycle: `start_experiment_draft`, `add_page_to_experiments`, `remove_page_from_experiments`, `generate_experiment_draft`, `regenerate_experiment_draft`, `edit_experiment_draft`, `publish_experiment_draft`, `discard_experiment_draft`, `cancel_draft_generation`, `resolve_experiment_decision`, `end_experiment`, `approve_draft_slug`, and `keep_current_slug`.
- Settings: `update_project_features`, `update_project_settings`, and `update_workspace_defaults`.

Project creation, rename/domain changes, archive, default-Project changes, and integration binding are not available in MCP v1.

## Admin marketing CMS tools

These eight tools are dynamically visible only when the authenticated user's root record currently has `admin: true`. Removing admin access hides them on the next request and blocks pending admin plans. Admin write tools additionally require `mcp:write`.

| Tool | Access | What it does and when to use it |
|---|---|---|
| `marketing_cms_list` | Admin + `mcp` | Lists compact localized page groups with type/status filters, versions, category relationships, pending changes, and each locale's path and publication state. Use to find content without loading full bodies. |
| `marketing_cms_read` | Admin + `mcp` | Reads one group by content ID or canonical English path, including editable drafts, versions, derived paths, link manifests, media references, and preview URLs. |
| `marketing_cms_validate` | Admin + `mcp` | Runs the complete publication dry run and returns locale, schema, path, dependency, canonical-link, and media issues. Use before preparing publication. |
| `marketing_cms_prepare_change` | Admin + `mcp:write` | Prepares a 30-minute CMS plan for `create_locale_group`, `replace_locale_draft`, `replace_all_locale_drafts`, `publish_locale_group`, `unpublish_locale_group`, or `discard_never_published_group`. Execute it with `actions_execute`. |
| `marketing_media_list` | Admin + `mcp` | Searches safe first-party media with dimensions, metadata, readiness, creator, and reference counts. It never returns bytes or storage credentials. |
| `marketing_media_prepare_upload` | Admin + `mcp:write` | Freezes filename, MIME type, decoded byte size, alt text, and caption into a one-time image upload plan. Use before sending image bytes. |
| `marketing_media_upload_image` | Admin + `mcp:write` | Executes a pending upload plan using plain base64. It rechecks size, extension, MIME, signature, ownership, expiry, and one-time state. |
| `marketing_media_prepare_change` | Admin + `mcp:write` | Prepares `replace_metadata` or `delete_unreferenced` for one media item. Deletion is allowed only at a current reference count of zero; execute with `actions_execute`. |

CMS creation and structural edits operate atomically on exactly `en`, `es`, `pt-BR`, `de`, and `fr`. Tools accept complete bodies, not arbitrary patches or database fields. All locales must retain the same ordered canonical English internal-link targets, and authored localized URLs are rejected. Publishing and unpublishing always affect the whole locale group.

Image upload supports JPEG, PNG, WebP, AVIF, GIF, and SVG up to 20 MB. Video upload remains in the Admin UI. Upload bytes go only to `marketing_media_upload_image`; they are never stored in an action plan or telemetry.

## Manage or revoke a client

Open **Settings → Account → MCP access** to see each client name and trust source, approved scopes, connection date, last use, and call totals. A client registered dynamically is labeled unverified unless its metadata came from a verified client metadata document.

Choose **Revoke** to invalidate every access and refresh token in that grant immediately. Reconnect from the MCP client if you revoke it by mistake.

## Troubleshooting

- **The client says the URL cannot load and never opens sign-in or consent**: confirm you added an MCP/custom connector, not a normal web connector. The client must support remote Streamable HTTP plus OAuth discovery and dynamic client registration or client metadata documents. Fetching `/mcp` as a web page does not connect it.
- **The client reports `redirect_uris must only contain web uris`**: the server rejected the client's desktop or mobile callback before authorization began. Update the deployment, then remove and reconnect the client so dynamic registration runs again with native callback support.
- **You want to verify the deployment**: open `https://serpclimber.com/.well-known/oauth-protected-resource/mcp`. It should return JSON naming `https://serpclimber.com/mcp` and the `https://serpclimber.com/oauth` authorization server. An unauthenticated MCP `POST` should return `401`, not an HTML 404.
- **The client receives `401`**: reconnect so it can discover OAuth and request a new token. Confirm the server URL ends in `/mcp`.
- **The client receives `403 insufficient_scope`**: reconnect and approve `mcp:write` if the tool is paid or can change data.
- **A tool returns a subscription or project error**: fix the plan, usage, or project access in SERPclimber. Do not delete and recreate the OAuth connection.
- **An integration-backed section is unavailable**: open **Integrations** and connect or repair Google, Wix, or Cloudflare. Workspace overviews keep returning their other lenses.
- **Authorization does not open**: the production deployment must have a stable HTTPS origin and configured private MCP OAuth cookie and signing keys.