API reference

Plug an agent in

One stateless endpoint, 43 tools (read-only by default, two confirmed writes), structured results. Connect Claude, Cursor or any Streamable HTTP client with a scoped key.

Updated 2026-11-08

On this page

MCP · tools & access

One stateless endpoint, 43 tools — 41 read-only plus 2 opted-in write actions guarded by confirm + idempotency. Connect a client once and let it answer “how is this project doing, and what should I fix next?” with real audit data. Read calls are free and rate-limited, not metered against the API quota.

Want the method, not just the tools? Read the Agent Skill — a read → fix → verify playbook with task references.

Let your assistant do the setup

Copy this page as Markdown and paste it into Claude, Cursor, Codex or any assistant. It carries the endpoint, both auth paths, the per-client configs and the tool list, so the assistant can wire your client and confirm tools/list works. A prompt that gets it done: “Set up the Visdenda MCP server for me using this guide.”

Connect a client

OAuth (recommended): add the URL in your client and choose sign-in. You approve specific sites and read scopes on the consent page, and can revoke the connection under Access → Connected apps. Tokens last 1 hour, refresh for 30 days, and ask for fresh consent after 90 days.

API key: create one in the console and send it as a Bearer header. Use audits:write only when you want the write tools. Native Streamable HTTP clients use the URL directly; desktop clients that only speak stdio go through mcp-remote. Paste the config for your client below, or copy this page into your assistant and let it do the wiring.

Shell

claude mcp add --transport http visdenda \
  "https://visdenda.com/v1/mcp"

TOML

[mcp_servers.visdenda]
url = "https://visdenda.com/v1/mcp"

JSON

{
  "mcpServers": {
    "visdenda": {
      "url": "https://visdenda.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SEO_WATCH_KEY}"
      }
    }
  }
}

JSON

{
  "mcpServers": {
    "visdenda": {
      "httpUrl": "https://visdenda.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer $SEO_WATCH_KEY"
      }
    }
  }
}

JSON

{
  "mcp": {
    "servers": {
      "visdenda": {
        "type": "http",
        "url": "https://visdenda.com/v1/mcp"
      }
    }
  }
}

JSON

{
  "mcp": {
    "visdenda": {
      "type": "remote",
      "url": "https://visdenda.com/v1/mcp"
    }
  }
}

JSON

{
  "mcpServers": {
    "visdenda": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://visdenda.com/v1/mcp",
        "--header", "Authorization: Bearer $SEO_WATCH_KEY"
      ]
    }
  }
}

JSON

{
  "mcpServers": {
    "visdenda": {
      "type": "streamable-http",
      "url": "https://visdenda.com/v1/mcp",
      "headers": { "Authorization": "Bearer $SEO_WATCH_KEY" }
    }
  }
}

Try asking your assistant:

Which sites need attention right now?
What should I fix first on my site?
What changed since the last audit?

Tools

Tool	Scope	What it does
audit_url	audit:read	Check one URL, or verify a fix against that site's last audit run.
get_radar_updates	radar:read	Recent P0/P1 updates with active-rule counts.
list_sites	audit:read	Sites under this key, their verify state and latest run.
get_portfolio	audit:read	All sites under the key, attention order, open totals.
get_project_status	audit:read	One-call snapshot: runs, changes, priorities, radar, GSC archive.
get_audit_findings	audit:read	Findings for a site (latest run or by run id).
diagnose_site	audit:read	Ranked to-fix list: failing rules × pages, linked updates.
get_audit_history	audit:read	Recent audit runs with status, summary and coverage.
get_audit_trends	audit:read	Pass/fail/na trend across runs, fixed vs regressed.
get_finding_lifecycle	audit:read	Open finding backlog with age buckets and recent resolutions.
get_site_health	audit:read	0–100 health score with four explainable penalties.
compare_audit_runs	audit:read	Any two runs: added/fixed/regressed and per-run totals.
explain_finding	audit:read	One finding plus rule doc and guidance.
get_update_impact	audit:read	One update × one site: linked rules and findings.
get_site_fingerprint	audit:read	Technology fingerprint (cached when fresh).
get_site_i18n	audit:read	i18n maturity L0–L4 with gaps.
get_gsc_monthly	audit:read	GSC monthly archive row, or na with reason.
get_gsc_overview	audit:read	GSC clicks, impressions, CTR and position with prior-period deltas.
get_gsc_queries	audit:read	Top search queries by clicks, with deltas.
get_gsc_pages	audit:read	Top landing pages by clicks, with deltas.
get_opportunities	audit:read	Fail-weighted fix opportunities, score ordered.
get_ai_traffic	audit:read	What AI crawlers and AI referrals actually did: hits, robots violations, markdown.
get_aio_visibility	audit:read	Latest AI Overview presence and citations; paid plans add sampled trend.
run_audit	audits:write	Start a full audit now (costs 1 audit run; confirm + idempotency key).
import_sitemap	audits:write	Add sitemap pages to the audit list (confirm + idempotency key).
verify_fix	audits:write	Re-check one finding and close it as fix-applied when it passes.
get_page_report	audit:read	One URL across search, visitors, AI fetches, AI visits, index, findings and CWV.
get_traffic_pages	audit:read	Per-page join of clicks, average position, sessions, AI fetches, AI visits and open findings.
get_crawler_gaps	audit:read	Paths crawlers asked for that 404 or are blocked, plus machine-file reads.
get_competitor_changes	sites:read	Competitor sitemap events (added, removed, lastmod) over the last N days.
get_competitor_feed	sites:read	Competitor pages with content-match tier, own-page matches, excerpt and triage state.
get_competitor_gaps	sites:read	Competitor pages with no matching own page, worst gaps first.
get_competitor_brief	sites:read	30-day brief per competitor: new pages, coverage, themes, gaps, pace.
get_competitor_rank	sites:read	Latest keyword-compare top-10 standings for your site vs competitors.
get_competitor_discovery	sites:read	Competitor candidates from the top 10 of your tracked keywords.
get_serp_results	research:write	Live Google SERP results for up to 10 queries, cached 12h.
get_keyword_metrics	research:write	Volume, difficulty and CPC for tracked keywords (30-day cache).
research_keywords	research:write	Keyword ideas from up to 5 seeds, cached 24h.
check_ai_visibility	research:write	AI Overview presence for tracked terms, reusing same-day samples.
estimate_research_cost	research:read	Preflight a paid research call: cache hits and estimated cost.
list_research_reports	research:read	Saved SERP, keyword and AI-Overview research reports.
get_research_report	research:read	One report plus GSC, AIO and tracked-keyword context.
get_site_insights	audit:read	Ranked insights with evidence, impact and what could not be checked.

Auth & limits

Handshake methods (initialize, notifications/initialized, tools/list, ping) and GET /v1/mcp need no key.
tools/call takes the smallest scope that does the job: audit:read for site and URL tools, radar:read for get_radar_updates.
Missing key and insufficient scope both answer 401 with JSON-RPC code -32002.
Read-only calls are free: they do not consume the REST API's monthly read quota.
Anti-abuse caps per account (or key, when no account owns it), per UTC day: 2,000 calls, 50 network fetches (audit_url, fingerprint, i18n), and 100 GSC live reads on paid plans. Free plans read archived GSC months only; archived months are free on both plans. Over a cap: HTTP 429, JSON-RPC -32003, data.code MCP_DAILY_LIMIT.
A per-key burst budget of 100 requests/minute answers 429 with data.code RATE_LIMITED.
Write tools (run_audit, import_sitemap) need audits:write, confirm:true and a unique idempotencyKey (1–128 chars). Without confirm they return a dry-run preview; the same key replays the first result for 24h. They consume the site's audit/sitemap quota, not the API read quota.
Argument errors are free; network-tool failures count because the fetch already happened.

Protocol

Streamable HTTP, stateless JSON responses — no SSE stream, so GET /v1/mcp answers 405. tools/list carries JSON Schemas and readOnly/destructive annotations; successful tools/call results include structuredContent next to a one-line summary, and business failures set isError. OAuth clients discover the issuer through the protected-resource metadata and authorization-server metadata.

Discovery: server card and AI catalog. The key is provisioned by an admin or self-served in the console — see authentication.