SE Ranking MCP: control your AI agent research costs

Start with one small task

The first run can answer a useful question: which of these terms deserves a closer look for our existing site? It doesn't require an agent to research every competitor, generate a content calendar and check AI visibility on its own initiative.

Use SE Ranking for your SEO research

What you need before connecting

SE Ranking is our starting point here because it supplies the domain and keyword data this workflow needs through a hosted MCP server. You still need suitable account access. Connecting a client doesn't grant access to every SE Ranking product, and the official documentation says that not every API endpoint is available through MCP.

Have your domain, a relevant search competitor and a short keyword list ready. Choose one country database. US and UK results are different research inputs, even when both sites are in English.

This is a documentation-based workflow, not a report of a paid test across three clients. We haven't measured the cost of the example below. The quantities are deliberately chosen teaching limits, not vendor plan allowances.

For broader buying questions, see our SE Ranking pricing guide. Here, the job is to control an actual research session rather than reproduce a subscription table.

Which costs and permissions need attention?

An MCP connection is a route to tools. It isn't a separate promise of unlimited data or a read-only account.

The official MCP documentation supports OAuth and API-key authentication. A key supplied in the X-Api-Key header has the same access as the account; restricted or read-only API keys aren't available according to that documentation.

Keep account-changing operations out of this research task. That includes creating projects or modifying keyword lists, not only operations whose names contain “delete.” Review the actual tools exposed to your client. A friendly tool name doesn't restrict access.

Use client tool controls where available, and leave paid operations subject to approval. A prompt is an instruction, not a hard spending cap. If you need a guaranteed maximum and cannot establish an enforceable limit for the selected operations, don't start the paid run.

Create a small input manifest

Put the job in a dedicated local folder. The folder is your evidence trail, not a place to store credentials.

The number 20 controls the example's size. It doesn't guarantee any particular credit charge. Related-keyword discovery, pagination and a second country's database are separate additions to the task.

If you already have Search Console data, use it to choose candidate terms and existing pages. Third-party estimates don't replace your own impressions or clicks. Our competitor analysis guide explains how to distinguish a search rival from a business rival.

Claude Code, Codex and Cursor: connect once, then use the shared workflow

SE Ranking documents all three clients. They use the same hosted endpoint, https://api.seranking.com/mcp, with Streamable HTTP, but their configuration files and permission controls differ.

Use the current SE Ranking setup instructions for your client. OAuth avoids pasting a raw API key into a command example. If you need key-based authentication, use your client's supported secret-handling mechanism and keep the value out of chat, source control and exported evidence.

One documentation wrinkle deserves a warning. The provider's Codex section includes an experimental MCP-client flag. The current Codex MCP guide describes HTTP support directly; don't add an old experimental flag simply because a copied snippet contains it. Check your installed version's current documentation.

Codex documents tool allowlists, denylists and approval policies. Don't copy those TOML options into Claude Code or Cursor. Verify each client's controls independently. The prompts below share the task logic; that doesn't make tool selection, permissions or output identical across clients.

Prompt 1: plan the work without paid research

Paste this after filling in the manifest. Inspecting a locally available tool catalog is different from executing a data query. If the client proposes a remote diagnostic that could be billed, it must ask first.

Read the input manifest in this project folder. Do not execute paid data
queries or change any remote account settings.

Inspect the available SE Ranking MCP tool descriptions. Identify the
read-only operations needed for one domain, one competitor, the supplied
keywords and the selected country. Do not infer unavailable tools.

Write RUN-PLAN.md with the exact proposed tool names, arguments, row/page
limits, required access and current documented billing basis. Mark missing
cost information unknown. Separate SE Ranking credits from model costs.

Propose only the smallest useful job. No automatic keyword expansion,
pagination, retries, AI Search or extra countries. Explain any data we can
reuse. List the output files and the conditions that would require a new
approval. Stop for my approval before paid execution.

Read the plan. “I'll do keyword research” is too vague. You should be able to see which domain, which terms and how many result pages the agent intends to request. If the plan needs an unavailable tool, reduce the task instead of letting the agent silently switch providers.

Prompt 2: execute only the approved plan

Give approval for a specific plan revision. Don't approve an open-ended objective and expect the manifest to police it perfectly.

Execute only the RUN-PLAN revision I explicitly approved. Use only its
permitted SE Ranking operations, targets, country and result limits.
No project changes, additional providers, scope expansion or automatic
paid retries. If an approved request fails, record the outcome and stop
before replacing or repeating it.

Save each source response or the raw output available from the client,
with its operation, arguments and retrieval time. Do not save secrets.
If raw export is unavailable, state that limitation; don't reconstruct
raw data from a summary. Reuse already-saved valid results.

Create keywords.csv with keyword, country, metric name/value as actually
returned, source_file, retrieved_at and an uncertainty note. Preserve
missing values as unknown rather than zero. Keep returned metrics separate
from your judgments. Write a short decision note mapping terms to an
existing page, a possible new page or no action. Stop when approved work
is complete or when a new paid action is required.

A keyword difficulty score is a screening input, not a ranking forecast. Before proposing a new page, compare its intent with your existing inventory and inspect the pages ranking for it. A term already served by a good page may call for an update instead.

Don't ask the agent to invent missing metrics to finish a tidy CSV. An empty cell with a reason is more useful than a plausible number.

Prompt 3: reconcile the evidence and the bill

The last step catches a surprisingly common mistake: a confident report whose figures can't be traced back to anything.

Audit this run using only saved evidence and approved, non-billed account
information already available. Do not issue another paid research query.

For every numeric claim, identify its source file and country. Flag
missing, inconsistent or unsupported values. Confirm the final work stayed
within the approved targets and result limits.

Complete COST-LEDGER.csv: operation, arguments_reference, status,
billing_basis_source, balance_before, balance_after, reported_charge,
attribution_status and notes. Use unknown where data is unavailable.
A shared-account balance difference is not automatically this run's cost.
Separate verified vendor charges, estimates and model usage.

Produce CHECKS.md listing passed checks, unresolved issues and which
additional actions need approval. Do not publish, update the website or
turn the research into an automatic recurring job.

If balance information requires an extra operation, verify whether that operation is free and authorised before using it. Don't spend credits trying to prove that a small job was cheap.

What a finished run should contain

Open the folder before accepting the answer. There should be a manifest, the approved plan, available raw responses, keywords.csv, COST-LEDGER.csv and a short review note. These are proposed output names, not files the provider creates automatically.

Check that every row names its country and source; no extra competitor appeared; missing metrics remain unknown; and recommendations distinguish estimates from facts about your own site. Cost records should make uncertainty visible. A zero in the charge column means verified zero, not “the agent couldn't find the bill.”

An illustrative failure and recovery

Suppose the domain response is saved, but the keyword request times out. The client suggests retrying with a larger result limit. Decline that escalation until you've checked what happened.

Keep the successful response. Record the timed-out operation, its arguments and any request identifier. A client timeout alone doesn't prove the provider charged nothing. Check the available account record without issuing another paid research request. If billing attribution is unresolved, mark it unknown.

Then choose between approving one bounded retry, reducing the keyword list or ending with a partial report. Resume from the saved evidence rather than restarting the whole workflow. This is an illustrative recovery scenario; we didn't reproduce it against the paid API.

Download the offline companion files

Download the research plan, prompts and cost-ledger templates. The package contains no credentials and makes no API calls by itself. Fill the inputs before approving a paid run.

Start with one decision

A useful first MCP job ends with a small, traceable answer. Choose a handful of terms, inspect the evidence and decide what deserves further work. Expand only after you understand the access and spending involved.

Connect SE Ranking for a controlled research task

For other data-provider choices, read our Ahrefs API alternatives guide. If you're still choosing an agent-assisted SEO setup, start with our AI SEO tools comparison.