# Scope MCP documentation

> Developer documentation for the Scope MCP server. Streamable HTTP, Bearer API key or OAuth. Reads are free. Actions echo check cost before they spend.

Canonical page: https://scope.online/docs

## Quickstart

- 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
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.

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

Setup page: https://scope.online/agents/cursor

### 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.

```
https://scope.online/mcp
```

Setup page: https://scope.online/agents/claude

### Any MCP client
Any client that speaks Model Context Protocol works with Scope. The raw 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 reference: https://scope.online/agents/tools (markdown: https://scope.online/agents/tools.md).

### 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

| 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 (ClawHub / OpenClaw): https://scope.online/agents/skill.md
- Permissions: https://scope.online/agents/security
- Product hub: https://scope.online/agents (markdown: https://scope.online/agents.md)