# Connect Claude or ChatGPT (MCP)

> How to connect Claude, ChatGPT or other AI tools to your Rankfinity data over MCP, what they can read, and how changes and paid actions are protected.

## What MCP is

MCP (Model Context Protocol) is an open standard that lets AI assistants use tools from other apps. With the Rankfinity connector, Claude, ChatGPT and other MCP-capable tools can look up your projects in plain language: "How did my rankings change this week?", "Which prompts mention my competitors in AI answers?", "Summarise the site audit for oak-and-iron.example".

The connection is **read-only by default**.

## Connecting

Open **My account › Connected apps** (the card **Connect Claude, ChatGPT or any AI assistant**). Copy the **Server URL** shown there. No token is needed: you sign in to Rankfinity and click **Allow**. The connection is read-only until you turn on **Allow changes**.

### Claude (web, desktop, phone)

1. In Claude open **Settings → Connectors → Add custom connector**.
2. Paste the Server URL, then click **Add** and **Connect**.
3. Sign in to Rankfinity in the window that opens and click **Allow**.

### ChatGPT

1. In ChatGPT open **Settings → Connectors** (Apps) and click **Add**.
2. Name it `Rankfinity`, paste the Server URL and choose **OAuth**.
3. Sign in to Rankfinity in the window that opens and click **Allow**.

### Claude Code and other tools

Run the command shown on the card, then type `/mcp` inside Claude Code and sign in. Other apps: paste the Server URL. For tools that let you set a header instead of signing in, open **Advanced: tokens for scripts**: give the token a name, click create, and copy it. The token is shown once. Send it as a bearer token in the header described there.

> **Note:** Treat a token that was shown on screen, in a screenshot or pasted into a chat as leaked. Revoke it and create a new one.

### Troubleshooting

Only if your app asks for addresses by hand (normally it finds them itself): the card's **Troubleshooting** section lists the Authorization URL (`/oauth/authorize`), Token URL (`/oauth/token`), Registration URL (`/oauth/register`) and Scope (`mcp:read`), each on the same host as the Server URL. The only address you paste is `/mcp` (streamable HTTP; `/mcp/sse` does not exist).

## What the assistant can read

Read tools cover almost everything you can see in the app, for the projects your account can access:

- **Projects:** list, summary, the All projects table, plan and usage.
- **Rank tracking:** positions, history, movers, distribution, ranking URLs, the top 10 results for a keyword, groups, and the full list of tracked keywords (`list_keywords` — every keyword, checked or not, with its location, in pages).
- **Map:** latest scan, scan points, scans list, coverage trend, compare two scans, map competitors.
- **AI visibility:** summary, any period, runs, run metrics, answers per prompt, cited sources, gaps, AI Overviews from rank tracking, and the platform settings with the Claude answer model and its price per answer (`ai_settings`).
- **Business Profile:** the monitor over time - rating, reviews, photos, profile changes, competitors (`gbp_monitor`).
- **Site audit:** summaries, checks, pages, a single page, action plan, compare two crawls, the crawl schedule (`site_audit_schedule`), outgoing links (`outgoing_links`), the latest crawl as a spreadsheet link (`site_audit_sheet`, free); Core Web Vitals; indexing status; bot visits.
- **Keywords and locations:** keyword clusters of the tracked keywords (`keyword_clusters`); `location_search` finds a city, country or region for a keyword, free.
- **Competitors and backlinks:** organic competitors, saved snapshots, and broken backlinks (`broken_backlinks`, the saved copy).
- **Saved research per project (free, nothing is looked up again):** `keyword_research_saved`, `backlinks_saved`, `content_gap_saved`, `domain_overview_saved`, `index_checks` and `gbp_overview` return what was last looked up for a project - or say "not available" and why. A new lookup costs credits and is made in the app.
- **Search Console and Google Analytics:** overview, keywords, pages, countries, devices, traffic, cannibalisation, sites.
- **Content writer:** articles and a single article.
- **Daily watch**, alerts, alert settings, reports and report schedules, share links, team members.
- **Credits:** balance, history and spend this month — for account owners. Clients see "Billing is handled by your agency".
- **Project memory and saved reports:** `get_project_context`, `list_reports`, `get_report`, `list_report_templates` (see below).
- **These help docs:** `docs_search` finds the right page and section, `docs_read` returns it (whole page or one section). Ask "how does Smart scan work?" or "what does share of voice mean?" and the assistant answers from the docs with a link, instead of guessing. In ChatGPT the same pages also come back from `search` / `fetch`.

When it connects, the assistant also receives a short guide from Rankfinity: which tool answers which kind of question, to pick your project by name without asking when it is obvious, that "not measured" is not zero, and that paid actions need your yes first. That is why you rarely need to name tools yourself.

Answers follow the same rules as the app: no data from projects you cannot see (they are simply "not found"), "not measured" where data is missing.

## Project memory

Every project has a short **memory** the assistant reads first (`get_project_context`), so a new conversation does not start from zero:

- **Business overview**, **Current goal**, **Positioning** and **Writing preferences** — a few paragraphs each (up to about 4,000 characters).
- **Custom sections** for anything else, such as a launch plan.
- A **competitor shortlist** and **key pages**, each with a note (up to 100 each).
- A **research log** — what was already researched or bought, with the date. The assistant checks it before paying for the same research again.

You can read and edit it in **Project settings › Project memory**. With **Allow changes** on, the assistant can update it too (`update_project_context`) — ask it to confirm facts with you before it stores them. Reading and writing the memory is free. Clients can read it but not change it.

## Reports from your AI assistant

When the assistant writes a report or an analysis you want to keep, it can save it in the project (`save_report`). Saved reports appear in **Reports › From your AI assistant**, where you can open, print, copy a link or delete them.

- The report is cleaned before it is stored: scripts, styles, images, forms and anything that runs code are removed. Headings, paragraphs, lists, tables, links and emphasis stay. It is shown in the Rankfinity report style, ready to print.
- New reports are private. A public link is created only when you ask for it (`set_report_sharing`), and switching sharing off stops the link at once. Your white-label settings apply to the public page.
- **Report templates** (`list_report_templates`, `save_report_template`) are short outlines the assistant follows, for example "Monthly client update". Saving, sharing and templates are free.

## Allow changes

If you want the assistant to also make changes, turn on **Allow changes** for that connection in **Connected apps**. A confirmation explains what it allows:

- Create projects (a website project without a map, so nothing is scanned). One project per website: if the site already has a project, the assistant gets that one back instead of creating a second.
- Rename a project and change its client name, language or location.
- Add or remove keywords. To track other cities or countries, the assistant adds keywords **with a location** to the same project (for example "add these 3 keywords for Varna and Burgas") — it does not create a project per city. Each keyword in each location is one tracked keyword and costs the same per check as any other.
- Deleting a project is **not** available through an AI connection. If you ask, the assistant tells you to open **Projects › the project's menu › Delete** in the app; nothing is changed.
- Add AI prompts (one by one or from CSV), enable, disable or delete them.
- Start a rank check, an AI visibility run or a site audit (`run_site_audit`, a crawl of the project's website; 2 credits per started 100 pages, and the price reply comes first).
- Schedule the site audit (`set_site_audit_schedule`): Off, Daily (only where your plan's limit allows a 1-day interval), Weekly, Every 2 weeks or Monthly, with a day, an hour in the project owner's time zone and the pages per crawl up to your plan's limit, and turn your crawl report email on or off. Saving is free and scheduled crawls are included in your plan. See [Site audit](/docs/site-audit).
- Link Search Console and Google Analytics 4 to a project (`google_properties`, `link_search_console`, `link_ga4`). This works only when your Google account is already connected in the app, and it is free. If the property name is not an exact match, the assistant asks you to pick.
- Update the project memory; save, share or delete AI reports and report templates.

Changes go through the same checks as the app, as you. Without **Allow changes** every write tool answers "This connection is read-only…" and touches nothing. Turn it off any time; the connection becomes read-only again immediately.

Reconnecting an app creates a new connection, which starts read-only.

### Paid actions always ask

Paid tools work in two steps:

1. The assistant asks for the price. Rankfinity replies with the price in credits and your balance — nothing is charged.
2. The assistant must call again with that exact price (`confirm_credits`). If the price changed in between, nothing is charged and you get the new price.

In practice the assistant tells you "A rank check for 40 keywords costs N credits — go ahead?" and waits for you.

### Daily limit

Daily limit for actions through AI connections (MCP): 2,000 credits (Agency: 5,000) — a safety cap.

- It counts the credits spent through **all** AI connections and tokens of your account together, per UTC calendar day (it resets at 00:00 UTC). Credits that come back (a failed run, pages that were not crawled) no longer count.
- The price reply already says how much of the limit is left today. An action that would go over it is refused and nothing is charged.
- The same action started in the app is not limited, and neither are scheduled checks.

Clients cannot make changes through MCP, even with **Allow changes** on.

## Ready-made skills

Beyond the data, the assistant can run finished pieces of work for you. It lists them with `list_skills` (the name, what each is for, its inputs and the price) and runs one with `run_skill`. Skills are paid like the other paid actions: the price comes first, and a run needs **Allow changes** on the connection.

| Skill | What you get | Credits per run |
|---|---|---|
| Local SEO audit brief | A one-page brief: what holds your map and search results back, ranked by effect. | 76 |
| AI visibility gap plan | A plan for the questions where AI assistants name rivals and not you, one change per group. | 76 |
| Content brief from a keyword | An outline for one keyword, built from the results that already rank for it. | 76 |
| Monthly client report summary | A two-minute summary: what changed, why, and three next steps. | 76 |
| Link building outreach plan | Where to earn links from, why, and a first outreach message for each kind. | 76 |
| Fix list from the site audit | The latest site audit as a prioritised fix list. | 76 |
| Growth plan | A detailed step-by-step plan from your own data: keyword groups, rivals, pages, links, the map, technical fixes, with priority, time window and how to measure. | 80 |
| Write an article | A full article through the Content writer, in steps: research first, then the draft. Read it with `content_article` when it is ready. | The same as in the Content writer |

You get the result of a skill, never how it works. The method behind each skill is not shared, and a request to see it is refused without a charge. A run that returns no usable text is not charged.

## Your growth plan through MCP

The **Plan** screen and the AI connection work on the same plan. The assistant can read it, tick tasks off and change it for you.

| Tool | What it does | Credits |
|---|---|---|
| `get_plan` | Reads the plan: goal, weeks, tasks with the reason, the steps, the tool and how each is measured, this week's tasks, and the numbers now against the start. A number that is not measured says so. | Free |
| `create_plan` | Builds a plan from your saved data (Search Console, rank checks, AI Visibility, site audit, map, rivals). It shows the price first; you confirm it. If nothing can be built, nothing is charged. | 80 (the same as the Plan screen) |
| `update_plan_task` | Marks a task To do, In progress or Done. **Done · verified** cannot be set this way: it appears only when the check after the change passes. | Free |
| `propose_plan_edit` | Suggests moving, adding or removing a task. The plan does not change yet. | Free |
| `apply_plan_edit` | Applies one suggested change, only when it is called after your yes. The Plan screen shows the same pending change. | Free |
| `dismiss_plan_edit` | Drops a suggested change you said no to. The plan stays as it was. | Free |
| `get_plan_pdf` | Gives a download link to the plan as a PDF - the same file as **Download PDF** on the Plan screen. The link works for a few minutes; ask again for a new one. | Free |
| `list_plans` | Lists the project's plans: the current one and the archived ones, with how many tasks were done. | Free |
| `archive_plan` | Archives the current plan, like **Archive this plan**. It stays in the list; you can create a new one any time. | Free |
| `what_to_do` / `update_what_to_do` | Reads the action list under the plan and marks an action To do, In progress or Done. | Free |

Changes need **Allow changes** on the connection. Building a plan counts toward the daily limit above; if you retry, give the same `idempotency_key` and you are not charged twice.

## More actions through MCP

| Tool | What it does | Credits |
|---|---|---|
| `run_map_scan` | Scans the map now, for all keywords or one. It shows the price first; you confirm it. | The same as **Scan** on the Map screen |
| `map_schedule` / `set_map_schedule` | Reads and changes how often the map is re-checked automatically (day, hour, keywords per scan, within your plan). | Free to save; scheduled scans are included in your plan |
| `run_domain_overview` | A domain overview now, for any domain. It shows the price first; a lookup you made recently is returned from your saved copy. | The same as **Domain overview** |
| `batch_analysis` | Compares up to the plan's limit of domains in one table (DR or rank, backlinks, referring domains, keywords, traffic, spam score). It shows the price first - only domains not checked in the last 30 days are charged. | 10 credits per 10 domains not checked recently |
| `run_keyword_clusters` | Groups a list of keywords into topics (keywords whose top-10 Google results overlap are one topic). It shows the price first. | 10 credits per new keyword; tracked and recently saved ones are free |
| `gbp_monitor_check` | Checks the Business Profile now, yours and your competitors' profiles. It shows the price first. | 10 credits per profile read |
| `set_ai_claude_answers` | Puts Claude's AI visibility answers on the Fast model (Claude Haiku 5.5, cheaper) or back on Standard. It changes the setting only; the next run is priced when it starts. | Free to save |
| `check_ai_content` | Checks a pasted text, a page address or a Content writer draft for AI-sounding writing and returns the score, the signals and the recommendations with rewrites. It shows the price first; you confirm it. | The same as **AI Content Checker** |
| `list_ai_content_checks` / `get_ai_content_check` | Reads the project's saved AI Content Checker results. | Free |
| `add_competitor` / `remove_competitor` | Adds or removes a competitor you track. | Free |
| `mark_alerts_seen` | Marks the project's alerts as read. | Free |

Changes need **Allow changes** on the connection. Paid actions count toward the daily limit above.

## Managing connections

**Connected apps** lists every connected app and token with its name, when it was created and last used, and whether changes are allowed.

- **Disconnect** removes an app's access immediately; it has to be connected again.
- **Revoke** stops a token immediately.

## Example questions

- "List my projects and the ones whose map ARP got worse this month."
- "For bright-dental.example, which keywords moved from page two to page one?"
- "Compare the last two site crawls and list new errors."
- "Which domains are cited most in AI answers for my prompts?"
- "Add these 10 keywords to the Riverside project" (needs Allow changes).
- "Why is my map average low for one keyword?"
- "Remember that our goal this quarter is the dental implants page" (needs Allow changes).
- "Write a competitor summary for Riverside and save it as a report" (needs Allow changes).

## Common questions

**Is MCP included in my plan?**
See **Billing › Compare plans** for the current list of plan features.

**Does reading data through MCP cost credits?**
No. Only paid tools (rank check, AI visibility run, site audit) cost credits, and only after you confirm the price.

**Can the assistant see my teammates' projects?**
It sees exactly what your account sees in the app.

**Why does the assistant say a project was not found?**
The project belongs to another workspace, was deleted, or the name is spelled differently. Ask it to list your projects first.

**Can I connect several assistants?**
Yes. Each connection is listed separately and has its own Allow changes switch.