Scope MCP Documentation

Quickstart

Point any MCP client at the Streamable HTTP endpoint. Authenticate with a Scope API key. Call whoami first.

Endpoint	https://scope.online/mcp
Transport	Streamable HTTP
Authorization	Bearer <SCOPE_API_KEY>
First call	whoami

Authentication

Two ways in: a restricted API key, or OAuth. Keys are created once in Settings and shown in full only then. Do not put a key in git, logs, URLs, or a shared chat.

API key — Authorization: Bearer sk_scope_…. Create one at https://app.scope.online/settings/api-keys.
OAuth — issuer https://scope.online/oauth. Used by Claude and ChatGPT connector flows.

Agent access is Growth-only. A tier_locked error means the account is not on Growth — relay the returned upgrade_url and stop.

Scopes

A new key defaults to every grantable scope and every business. Narrow businesses or features later without rotating the secret. A selected-business key cannot add new sites.

scope	label	what it allows
read	Read reports	Visibility, citations, competitors, and recommendations. Always granted.
scan:run	Spend checks	Run scans and test prompts that use the check pool.
prompts:write	Change tracked prompts	Start or stop monitoring prompts.
business:create	Add businesses	Add new sites to this account. Requires an all-businesses key.
business:write	Draft and complete fixes	Generate drafts and mark recommendations done. Never publishes to the site.

Connect

Cursor JSON, Claude connector, or any MCP client. Same endpoint in every case.

Cursor

Drop Scope into .cursor/mcp.json and let Cursor pull visibility scores, citations, and draft schema fixes while you ship. One MCP endpoint, restricted API key.

Cursor MCP config

{
  "mcpServers": {
    "scope": {
      "url": "https://scope.online/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SCOPE_API_KEY"
      }
    }
  }
}

Cursor setup

Claude

Add the Scope MCP server to Claude to monitor AI visibility, run readiness checks, and draft GEO fixes — without leaving chat. Complements your existing SEO program.

MCP endpoint

https://scope.online/mcp

Claude setup

Any MCP client

Any client that speaks Model Context Protocol works with Scope. The raw contract:

Raw MCP contract

Endpoint   https://scope.online/mcp   (Streamable HTTP)
Auth       Authorization: Bearer YOUR_SCOPE_API_KEY
           (new keys: all businesses + all grantable permissions)
Tools      16 · reads free · actions echo checks cost first

CLI package: https://scope.online/scope-mcp-0.1.0.tgz

Tools

19 tools. Looking is always free. Full schemas, when-to-use, and examples live on the tool reference (markdown).

See

id	cost	scope
whoami	Free	read
list_businesses	Free	read
get_visibility_report	Free	read
get_ai_traffic	Free	read
get_scan	Free	read
get_prompt_results	Free	read
get_citations	Free	read
get_citation_briefs	Free	read
get_crawler_visits	Free	read
get_competitors	Free	read
get_recommendations	Free	read
get_readiness_score	Free	read

Do

id	cost	scope
add_business	Free	business:create
run_scan	1 check per tracked prompt	scan:run
check_prompt	Exactly 1 check	scan:run
track_prompt	Free now — adds committed burn	prompts:write
untrack_prompt	Free	prompts:write

Fix

id	cost	scope
generate_fix	Free	business:write
complete_recommendation	Free	business:write

Checks

A check is one prompt evaluated across all supported engines.

check_prompt spends exactly one check. run_scan spends one check per tracked prompt included.

Adding a prompt with track_prompt is free at that moment — its cadence creates committed burn (monthly cadence commits 1 check/month; weekly commits about 4/month).

Every response that spends checks returns checks_spent and checks_remaining — relay them to the human, and warn at 80% pool use.

There is no publish_fix tool. Scope agents draft fixes; they never publish directly to a website or CMS.

Errors

Every error is a JSON-RPC error with a stable machine-readable code.

code	status	meaning
invalid_request	400	Malformed or missing required arguments.
unauthorized	401	Missing, expired, or invalid API key / OAuth token.
insufficient_scope	403	The key or token is missing a required permission (e.g. business:create).
tier_locked	403	The account is not on Growth. Relay the returned upgrade_url and stop.
not_found	404	The business, prompt, or recommendation ID does not exist on this account.
rate_limited	429	Too many requests. Respect retry_after (seconds) before retrying.
quota_exceeded	402	The account's check pool is exhausted. Do not retry or split the action.
over_committed	402	Existing tracked prompts already exceed the plan pool. Offer to reduce cadence.
internal_error	500	Unexpected server error. Safe to retry once.

Rate limits

Read tools

60 requests / 60 seconds

per authenticated user

Action tools

10 requests / 60 seconds, 500 / day

per authenticated user

Anonymous readiness check

5 requests / 24 hours

per source IP

A rate_limited response includes retry_after in seconds.

Skill & security

Skill-based runtimes (ClawHub, OpenClaw): install https://scope.online/agents/skill.md.
What a connected agent can and cannot do: permissions and data handling.
Product overview for operators: Scope for agents.