MCP for Cursor and AI agents

Connect Cursor (or any Streamable HTTP MCP client) to your SEO Perception workspace. Tools read stored weekly Search Console facts and crawl data only — never live Google calls from MCP.

Full setup guide: MCP for Cursor docs. Machine endpoint: https://seoperception.com/mcp

Local-data promise

MCP never re-queries Google Search Console or URL Inspection.
Answers come from data SEO Perception already collected for your sites.
Your MCP client (for example Cursor) may still send returned evidence to its model provider — do not treat results as “never leave the machine.”
Paid plans only (Starter / Pro / Business / Enterprise). Free accounts cannot create tokens.

Personal access tokens

Create and revoke MCP tokens in your account settings. Secrets are shown once; store them as SEOPERCEPTION_MCP_TOKEN.

Cursor setup

Add this to ~/.cursor/mcp.json or project .cursor/mcp.json, then set SEOPERCEPTION_MCP_TOKEN in the environment Cursor inherits.

{
  "mcpServers": {
    "seo-perception": {
      "url": "https://seoperception.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SEOPERCEPTION_MCP_TOKEN}"
      }
    }
  }
}

Server card: https://seoperception.com/.well-known/mcp/server-card.json

Tool status

Only Available tools appear in tools/list. Planned tools are documented for roadmap clarity. Excluded tools will not ship on MCP.

Available

Tool	Status	What it does
`seoperception_list_sites` List sites	Available	List owned websites with stored GSC and crawl freshness.
`seoperception_get_site_overview` Site overview	Available	Summarize stored search performance, leading pages, queries, and rank momentum.
`seoperception_search_queries` Search queries	Available	Search and filter stored query evidence by content match, CTR, position, and intent.
`seoperception_list_opportunities` SEO opportunities	Available	List bounded, evidence-backed crawl and Search Console possibilities.
`seoperception_find_cannibalization` Keyword cannibalization	Available	Find stored query conflicts and the deterministic preferred page.
`seoperception_find_content_gaps` Content and snippet gaps	Available	Find stored low-CTR, missing-query, title/snippet, question, and refresh opportunities.
`seoperception_suggest_internal_links` Internal-link suggestions	Available	Return stored destination and anchor opportunities without crawling or probing URLs.
`seoperception_get_page_diagnostics` Page diagnostics	Available	Combine one page’s crawl metadata, stored GSC trends, top queries, and possibilities.

Planned

Tool	Status	What it does
`seoperception_compare_periods` Period comparison	Planned	Compare explicit stored weekly periods with deterministic deltas.
`seoperception_find_content_decay` Content decay	Planned	Detect sustained stored click and position declines.
`seoperception_get_geo_breakdown` Country and device breakdown	Planned	Read stored country/device facts for Business and Enterprise sites.
`seoperception_generate_report` Hosted report	Planned	Create a bounded, shareable analysis artifact.

Permanently excluded

Tool	Status	What it does
`live_gsc_query_or_inspection` Live Google calls	Excluded	Direct GSC queries, URL Inspection, collection, and Google OAuth are permanently excluded.
`mutations_and_refreshes` Mutations and refreshes	Excluded	Recrawls, indexing writes, issue updates, PSI refreshes, and LLM generation are excluded.

Example prompts

Ask Cursor to use SEO Perception tools. Prefer observed evidence from tool results over invented recommendations.

List sites

“List my SEO Perception sites and tell me which data is freshest.”
Site overview

“Summarize the strongest gains and losses for my site using stored data.”
Search queries

“Find non-branded queries in positions 5–20 that are missing from their landing page.”
SEO opportunities

“Show the highest-priority open SEO opportunities and explain the evidence.”
Keyword cannibalization

“Find keyword cannibalization and recommend which page should be preferred.”
Content and snippet gaps

“Find title, snippet, and content gaps with the best realistic upside.”
Internal-link suggestions

“Suggest internal links and natural anchor text for pages with ranking potential.”
Page diagnostics

“Diagnose this page using its crawl state, titles, indexability, queries, and opportunities.”

Freshness and retention

GSC facts are stored as ISO weeks (Monday–Sunday) with tier-based retention.
Google can omit low-volume rows before we store them — treat stored evidence as complete for what we received, not as a perfect mirror of Search Console UI totals.
Crawl metadata (titles, canonicals, links, issues) updates when your site is crawled in SEO Perception.

Security

Personal tokens, not passwords

Use MCP tokens only. Never put your login password or session cookie in Cursor config. Manage tokens under Account → MCP.

Revoke tokens when a laptop leaves the company or a contractor finishes.
Token secrets are hashed at rest; we only store a short display prefix.
Site access is scoped to websites you own; unknown site IDs return not found.

Troubleshooting

401 — missing/invalid/expired token. Create a new one in Account → MCP and update the env var.
403 paid_plan_required — upgrade, then create a token again.
429 — rate limited; wait for the retry time in the response.
Empty query/issue lists usually mean no stored data yet — confirm GSC collection and crawl finished for that site.