# Copilot SEO: guide for AI agents

Copilot SEO (https://copilot-seo.com) imports a site's Google Search Console data and turns it into an Action plan: a short, ranked list of changes worth making, each with its evidence. When a change is recorded as made, it reviews the outcome 28 days later. It also measures experiments, draws annotations (releases, notes, Google updates) on the charts, and raises alerts when clicks, position or CTR move sharply.

This guide is for an AI agent helping a person get started. It covers what only the person can do, how to connect, how to set up an account, the questions to ask, the routines to suggest and the tools. Everything works through the MCP server or the REST API; each tool's own schema gives its exact arguments.

## The full guide

Once you are connected, read the full guide. It adds the rules for reading the data and each routine step by step. It comes with the connection, once the person has confirmed their email address:

- **MCP server:** the `copilot-seo://agents.md` resource, the `get_started` prompt, and a prompt for each routine.
- **REST API:** `GET https://copilot-seo.com/api/v1/guide` with the token, as Markdown.

## What only the person can do

Send the person these links and wait for them. Do not try to do these yourself.

1. **Create the account.** Copilot SEO is in early access: the person joins the list at https://copilot-seo.com/#early-access and we email them when their account is ready. They then confirm their email address; the tools refuse an account whose email is not confirmed.
2. **Connect Google** at https://copilot-seo.com/setup, signed in. Google's consent screen has to be approved in a browser, by a Google account that can see the site in Search Console. Copilot SEO asks for read-only access.
3. **Pay**, only if they need more than their plan gives (more sites, longer history, more experiments) at https://copilot-seo.com/billing. Plans and limits: https://copilot-seo.com/help/plans-and-billing.md. The free plan needs no card.
4. **Let you in.** Approve the sign-in screen when you connect over OAuth, or create a personal access token at https://copilot-seo.com/settings/api-tokens. Both ask for their password first.

Everything after that you can do through the tools.

## Connect

One set of operations, offered two ways. Both act as the person, across every team they belong to.

- **MCP server:** `https://copilot-seo.com/mcp` (streamable HTTP).
    - Claude.ai and Claude Desktop: the person adds it as a custom connector, then signs in and approves it. OAuth, nothing to copy.
    - Claude Code: `claude mcp add --transport http copilot-seo https://copilot-seo.com/mcp`, then `/mcp` and sign in through the browser.
    - Any other MCP client: sign-in only returns to Claude's own addresses or to a program on the person's computer (loopback). Elsewhere, use a personal access token, sent as `Authorization: Bearer <token>`.
- **REST API:** `https://copilot-seo.com/api/v1`, JSON, with the same personal access token as `Authorization: Bearer <token>`. `GET https://copilot-seo.com/api/v1` lists every endpoint. For code, scripts, cron and CI.

A personal access token is created by the person at https://copilot-seo.com/settings/api-tokens. It can always read. It can only change things if they ticked "Allow writes". `whoami` tells you which you have. For "report only" work, ask for a read-only token.

## Set up an account

1. `whoami`: check the connection works, see the person's teams and roles, and whether this token may write. Setting up needs a token that may write.
2. `setup_status`: for each team, which setup steps are done, what to do next, and which steps need the person, with the link to send them. Start from here whenever you are unsure where things stand.
3. If a step needs the person (no account, Google not connected, plan limit reached), send them its link and stop until they say it is done. Then call `setup_status` again.
4. Ask the questions in the next section before you add or change anything.
5. `list_search_console_sites`: the Search Console sites their connected Google accounts can see, with the ones already added marked. If it says no Google account is connected, send them the connect link it gives.
6. `add_site` for each site they chose. This starts the import. If a site has both a Domain property (`sc-domain:example.com`) and a URL-prefix property, prefer the Domain one; adding both counts as two sites and their numbers overlap. A refusal at the plan's site limit is a "pay" step for the person.
7. Wait for the import. Call `setup_status` (or `list_properties`, where `data_through_date` appears once data is in) every few minutes. A large site can take a while. The person also gets an email when their data is ready, so you can stop and pick up later.
8. `set_brand_terms` with the brand names they gave you, including misspellings and product names. Brand terms belong to the team and apply to all its sites. It replaces the team's list, so send the whole list. Only team owners and admins can set them.
9. `list_recommendations`: show the person the top of their Action plan (the `now` queue first) and explain the first action in plain words.
10. Suggest the routines that fit their goal (see Routines), agree how often, and set them up where you run.

## Questions to ask the person

Ask these once, early, in your own words. If you can keep notes between runs, keep the answers.

1. **Which sites?** Offer the list from `list_search_console_sites`.
2. **What are your brand names?** Company, product and people's names, and common misspellings. Used to split brand searches from the rest.
3. **What do you want from this?**
    - More clicks: suggest "Rewrite the five weakest titles", "Weekly Action plan digest" and "Decay watch".
    - Reporting and overviews: suggest "Weekly Action plan digest" and "Monthly report across sites".
    - Client work: suggest "Monthly report across sites" and "Onboard a new site" for each client.
    - Measuring a bigger change (a redesign, a new template, a site move): suggest "Experiment check-in".
4. **Can I edit the site?** Its code, its CMS, or neither. If neither, you draft changes and the person makes them. If the site deploys from a repository, suggest "Annotate every release".
5. **How hands-off do you want to be?**
    - Report only: you read and report, and change nothing. A read-only token is enough.
    - Suggest and ask (the default): you propose each change and wait for a yes before editing the site or writing to Copilot SEO.
    - Hands-off: you make the changes you agreed on, record them, and report afterwards.
6. **How often should I check in, and where?** Weekly, every two weeks or monthly; in this chat, by email, or in a document.
7. **Is anything seasonal, or already planned?** So you do not report an expected dip as a problem, or suggest work that is already under way.

## What Copilot SEO does on its own

You do not need to trigger these:

- It imports new Search Console data every morning, and refreshes the Action plan after each import.
- It reviews implemented actions once their 28 days of data are in.
- It analyses running experiments every morning.
- It raises alerts each morning, and emails a weekly report every Monday.

There is no tool to start an import, end an experiment or change billing. Those are in the app.

## Routines

Copilot SEO does not schedule or run routines. These are suggestions. Pick the ones that fit the person's goal, agree how often, and set them up in whatever you run in: a scheduled task in your agent app, a cron job or CI schedule calling the REST API, or a reminder for the person to ask you. If you cannot schedule anything, say so and give the person the prompt to paste each time.

Each routine below says who it is for, how often, what it is for and the tools it uses. The steps are in the full guide, and in the MCP prompt of the same name.

### Rewrite the five weakest titles

- **For:** Anyone who wants more clicks from the rankings they already have.
- **How often:** Monthly
- **Goal:** Find the pages with lots of impressions and a weak CTR for their position, draft new titles and meta descriptions, record each change once it is live, and next month report what moved.
- **Tools:** `get_outcomes`, `list_recommendations`, `gsc_metrics`, `mark_implemented`, `create_marker`, `create_experiment`
- **MCP prompt:** `weakest_titles`, with the steps in full

### Weekly Action plan digest

- **For:** Business owners, and anyone who wants a short list each week.
- **How often:** Weekly
- **Goal:** A short list of the changes most worth making this week, anything that moved sharply, and reviews of past changes that came back.
- **Tools:** `list_properties`, `sites_overview`, `list_recommendations`, `list_alerts`, `get_outcomes`, `update_recommendation`
- **MCP prompt:** `weekly_digest`, with the steps in full

### Annotate every release

- **For:** Developers, and anyone who ships changes to the site often.
- **How often:** After every release
- **Goal:** An annotation on the site's charts for every release, with the version and what changed, so a rise or fall can be read against it.
- **Tools:** `list_properties`, `create_marker`, `create_experiment`
- **MCP prompt:** `mark_releases`, with the steps in full

### Monthly report across sites

- **For:** Agencies, freelancers and anyone with several sites.
- **How often:** Monthly
- **Goal:** Every site side by side against the period before, what moved and why, and the next actions, written so it can be sent to a client.
- **Tools:** `sites_overview`, `gsc_metrics`, `list_url_groups`, `list_markers`, `get_outcomes`, `list_recommendations`
- **MCP prompt:** `portfolio_report`, with the steps in full

### Decay watch

- **For:** Sites with a lot of older content, such as blogs, guides and documentation.
- **How often:** Every two weeks
- **Goal:** The pages losing clicks, the searches they lost, what lines up in the annotations, and what to refresh.
- **Tools:** `list_recommendations`, `gsc_metrics`, `list_markers`, `mark_implemented`
- **MCP prompt:** `decay_watch`, with the steps in full

### Experiment check-in

- **For:** Anyone measuring a bigger change, such as a new template or a site move.
- **How often:** Every two weeks while an experiment runs
- **Goal:** How each running experiment is doing, in plain words, without calling a result too early.
- **Tools:** `list_experiments`, `get_experiment`, `list_markers`
- **MCP prompt:** `experiment_checkin`, with the steps in full

### Onboard a new site

- **For:** Anyone adding another site, or a new client.
- **How often:** Once for each site
- **Goal:** Add another site, wait for its import, set up URL groups for its main sections with the person, and show its first actions.
- **Tools:** `setup_status`, `list_search_console_sites`, `add_site`, `list_properties`, `set_brand_terms`, `gsc_metrics`, `create_url_group`, `list_recommendations`
- **MCP prompt:** `new_site`, with the steps in full

## Operations

Every operation exists as an MCP tool and as a REST endpoint under `https://copilot-seo.com/api/v1`, with the same inputs, outputs and rules. Writes need a token that may write.

| MCP tool | REST | Writes | What |
|---|---|---|---|
| `whoami` | `GET /api/v1/me` |  | The person, their teams and roles, and whether the token may write |
| `setup_status` | `GET /api/v1/setup` |  | Each team's setup steps, done or not, what to do next, and which need the person, with the link |
| `list_search_console_sites` | `GET /api/v1/google/sites` |  | Search Console sites the person's Google accounts can see, marking ones already added |
| `add_site` | `POST /api/v1/properties` | yes | Add a Search Console site to a team and start its import |
| `set_brand_terms` | `PUT /api/v1/teams/{team}/brand-terms` | yes | Replace a team's brand terms (owners and admins) |
| `list_properties` | `GET /api/v1/properties` |  | Sites with their ids and `data_through_date` |
| `sites_overview` | `GET /api/v1/sites/overview` |  | Every site side by side for a period against the one before, with a trend and actions in Now |
| `gsc_metrics` | `GET /api/v1/properties/{property}/metrics` |  | Clicks, impressions, CTR and position by query, page or date |
| `get_rankings` | `GET /api/v1/properties/{property}/rankings` |  | How many queries or pages rank in the top 3, the rest of page one, page two and beyond, each week, and what moved between them |
| `list_recommendations` | `GET /api/v1/properties/{property}/actions` |  | The Action plan, highest value first |
| `get_recommendation` | `GET /api/v1/actions/{recommendation}` |  | One action: diagnosis, evidence, how to act, status, review date |
| `update_recommendation` | `PATCH /api/v1/actions/{recommendation}` | yes | Move an action between Now, Next and Later, or dismiss it with a reason |
| `mark_implemented` | `POST /api/v1/actions/{recommendation}/implemented` | yes | Record that the change was made, with a note; starts the 28-day review and annotates the day |
| `get_outcomes` | `GET /api/v1/properties/{property}/outcomes` |  | Implemented actions with their reviews (before, after, verdict), and ones still waiting |
| `list_markers` | `GET /api/v1/properties/{property}/annotations` |  | Annotations: releases, notes, team-wide ones and Google updates |
| `create_marker` | `POST /api/v1/properties/{property}/annotations` | yes | Annotate a release or change; with a `ref`, calling again updates it |
| `delete_marker` | `DELETE /api/v1/annotations/{marker}` | yes | Delete an annotation on a site |
| `list_experiments` | `GET /api/v1/properties/{property}/experiments` |  | Experiments with their cached before and after |
| `get_experiment` | `GET /api/v1/experiments/{experiment}` |  | One experiment, analysed now |
| `create_experiment` | `POST /api/v1/properties/{property}/experiments` | yes | Start measuring a change to a page, a group of pages or the whole site |
| `list_url_groups` | `GET /api/v1/properties/{property}/url-groups` |  | Saved URL groups with totals for a period against the one before |
| `create_url_group` | `POST /api/v1/properties/{property}/url-groups` | yes | Save a URL group from rules (contains, starts with, exact, regex) and excludes |
| `list_alerts` | `GET /api/v1/alerts` |  | Recent alerts for a team, newest first |

## Read more

- The handbook, for what each feature does: https://copilot-seo.com/help. Every article is also plain Markdown at `https://copilot-seo.com/help/{slug}.md`, for example https://copilot-seo.com/help/action-plan.md.
- Index for agents: https://copilot-seo.com/llms.txt
- The MCP server in detail: https://copilot-seo.com/features/search-console-mcp-server
- For people: https://copilot-seo.com/agents