> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sitespy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect Site Spy to Claude Code, Codex, OpenCode, Cursor, and other MCP-compatible tools

Site Spy provides an [MCP server](https://www.npmjs.com/package/@site-spy/mcp-server) that lets AI assistants monitor websites, compare snapshots, and manage watches through natural language.

## Setup

Copy your API key from [Dashboard Settings > API & Monitoring](https://sitespy.app/dashboard/settings?tab=api),
then add the server to your client.

If your client has a CLI, that is the whole setup:

```bash theme={null}
# Claude Code
claude mcp add site-spy --env SITE_SPY_API_KEY=your-api-key -- npx -y @site-spy/mcp-server

# Codex CLI
codex mcp add site-spy --env SITE_SPY_API_KEY=your-api-key -- npx -y @site-spy/mcp-server

# Gemini CLI  (the -- matters: without it, -y is parsed as a gemini flag)
gemini mcp add -s user -e SITE_SPY_API_KEY=your-api-key site-spy npx -- -y @site-spy/mcp-server

# OpenClaw
openclaw mcp add site-spy --command npx --arg -y --arg @site-spy/mcp-server --env SITE_SPY_API_KEY=your-api-key

# VS Code
code --add-mcp '{"name":"site-spy","command":"npx","args":["-y","@site-spy/mcp-server"],"env":{"SITE_SPY_API_KEY":"your-api-key"}}'
```

Otherwise add this to the client's config file:

```json theme={null}
{
  "mcpServers": {
    "site-spy": {
      "command": "npx",
      "args": ["-y", "@site-spy/mcp-server"],
      "env": {
        "SITE_SPY_API_KEY": "your-api-key"
      }
    }
  }
}
```

Restart your AI client — Site Spy tools appear automatically.

## Configuration file locations

| Client                   | Path                                                              | Config shape                                               |
| ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------- |
| Claude Code              | `.mcp.json` in project root, or `~/.claude.json`                  | `mcpServers`, as above                                     |
| Claude Desktop (macOS)   | `~/Library/Application Support/Claude/claude_desktop_config.json` | `mcpServers`, as above                                     |
| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     | `mcpServers`, as above                                     |
| Cursor                   | `.cursor/mcp.json` in project root, or `~/.cursor/mcp.json`       | `mcpServers`, as above                                     |
| Windsurf                 | `~/.codeium/windsurf/mcp_config.json`                             | `mcpServers`, as above                                     |
| Gemini CLI               | `.gemini/settings.json` or `~/.gemini/settings.json`              | `mcpServers`, as above                                     |
| Codex CLI                | `~/.codex/config.toml`                                            | TOML table `[mcp_servers.site-spy]`                        |
| OpenCode                 | `opencode.json`, or `~/.config/opencode/opencode.json`            | `mcp` key, `command` is an array, env key is `environment` |
| OpenClaw                 | `~/.openclaw/openclaw.json`                                       | servers nest under `mcp.servers`                           |
| VS Code                  | `.vscode/mcp.json`                                                | `servers` key, with `type: "stdio"`                        |
| Zed                      | run the `zed: open settings file` action                          | `context_servers` key                                      |

The five clients whose shape differs have full snippets in the
[package README](https://www.npmjs.com/package/@site-spy/mcp-server).

## Available tools

Read tools are marked read-only, so most clients let them run without asking for
approval each time. Write tools are available on every plan, including Free.

### Read tools

| Tool                 | Description                                       |
| -------------------- | ------------------------------------------------- |
| `authenticate`       | Connect to Site Spy with an API key               |
| `auth_status`        | Check whether the MCP server is authenticated     |
| `list_watches`       | List all monitored websites                       |
| `get_watch`          | Get full details of a specific watch              |
| `get_change_history` | Get timestamps when changes were detected         |
| `get_snapshot`       | Get page content captured at a specific timestamp |
| `get_diff`           | Compare page content between two timestamps       |
| `search_watches`     | Search watches by URL, title, or content          |
| `get_rss_settings`   | Get RSS feed settings                             |
| `get_notifications`  | Get current notification settings                 |

### Write tools

| Tool                 | Description                        |
| -------------------- | ---------------------------------- |
| `create_watch`       | Start monitoring a URL for changes |
| `update_watch`       | Update a watch's configuration     |
| `delete_watch`       | Stop monitoring a URL              |
| `trigger_recheck`    | Force an immediate recheck         |
| `generate_rss_token` | Generate or regenerate RSS token   |
| `revoke_rss_token`   | Revoke RSS feed token              |

### Web tools

| Tool         | Description                                                                 |
| ------------ | --------------------------------------------------------------------------- |
| `fetch_url`  | Fetch one URL through Site Spy, with a browser backend for JavaScript pages |
| `web_search` | Search the web and return ranked result URLs to fetch                       |

### AI tools (Pro and above)

| Tool             | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `get_ai_summary` | Get AI-generated plain-English summary of the most recent change |

## Plan limits

MCP access follows the same plan limits as the REST API. Every plan can read and
write; what differs is how many watches you can hold and how many requests you get
a day. Reading does not count against the daily quota — only writes do:

| Plan     | Watches | Write requests/day | AI summary |
| -------- | ------- | ------------------ | ---------- |
| Free     | 2       | 100                | —          |
| Starter  | 25      | 1,000              | —          |
| Pro      | 100     | 10,000             | Yes        |
| Business | 500     | 50,000             | Yes        |

## Example usage

Once connected, you can ask your AI assistant things like:

* "What changed on my watches recently?"
* "Start monitoring [https://example.com/pricing](https://example.com/pricing) for price changes"
* "Show me the diff for my Amazon watch"
* "Summarize the latest change on my competitor's site"
* "Recheck all my watches"

## Troubleshooting

* **"Not authenticated" errors** — Make sure `SITE_SPY_API_KEY` is set correctly in the config. You can verify by asking the assistant to run `auth_status`.
* **"API key is invalid or expired"** — The key was revoked or regenerated. Copy a fresh one from [Settings > API](https://sitespy.app/dashboard/settings?tab=api) and update the config. Nothing is wrong with the server itself.
* **Tools not appearing** — Restart your AI client after adding the config. Ensure `npx` is available (requires Node.js 20.19+).
* **"Watch limit reached" errors** — You are at your plan's watch cap (2 on Free). Delete a watch or upgrade.
* **"Rate limit reached" errors** — You have used the day's write allowance. The error says how long to wait.
* **"Pro plan required" errors** — The `get_ai_summary` tool requires Pro or Business plan.