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

# MCP server

> Connect Claude Code, Codex, Cursor, Windsurf, Gemini CLI, VS Code, Claude or Grok to the Stophy MCP server with one command or URL, with or without an API key.

The hosted MCP server gives your agent Stophy tools to search, scrape, map, parse, crawl, extract, run agent tasks, drive browsers and watch pages. Add its URL to your client's MCP settings. It is not a web page.

To have your agent do this, paste: `Use curl to read https://docs.stophy.dev/agent-quickstart.md and connect the Stophy MCP server to this agent.`

## Choose how to connect

| Connect with | URL | You get |
| - | - | - |
| Browser sign-in | `https://mcp.stophy.dev/mcp` | Every tool. You approve the app in your browser, and calls spend your balance. |
| An API key | `https://api.stophy.dev/mcp` with `Authorization: Bearer $STOPHY_API_KEY` | Every tool |
| No key | `https://api.stophy.dev/mcp` | Search, scrape, map, parse and signup, within the [keyless limits](https://docs.stophy.dev/production/rate-limits.md#without-a-key) |

Clients that support MCP OAuth start the sign-in on their own. Signing out of stophy.dev disconnects the app. Clients and registries can read the server's URL and sign-in from [mcp.json](https://stophy.dev/.well-known/mcp.json).

## Add it to your client

These commands use browser sign-in. For no key or a key, use the `api.stophy.dev` URL.

```bash Claude Code theme={null}
claude mcp add --transport http stophy https://mcp.stophy.dev/mcp
# then run /mcp, choose stophy and pick Authenticate
```

```bash Codex theme={null}
codex mcp add stophy --url https://mcp.stophy.dev/mcp
codex mcp login stophy
```

```bash Gemini CLI theme={null}
gemini extensions install https://github.com/stophydotdev/stophy
# then run /mcp auth stophy
```

```json Cursor (~/.cursor/mcp.json) theme={null}
{ "mcpServers": { "stophy": { "url": "https://mcp.stophy.dev/mcp" } } }
```

```json Windsurf (mcp_config.json) theme={null}
{ "mcpServers": { "stophy": { "serverUrl": "https://mcp.stophy.dev/mcp" } } }
```

```bash OpenCode theme={null}
opencode mcp add stophy --url https://mcp.stophy.dev/mcp
# then run /mcps, choose stophy and sign in
```

```bash VS Code (no key) theme={null}
code --add-mcp '{"name":"stophy","type":"http","url":"https://api.stophy.dev/mcp"}'
```

Restart Cursor after you edit its file. In Windsurf, open the file with **Open MCP config file** in the Cascade MCP menu. If you see two `stophy` servers in Claude Code, run `claude mcp remove stophy` and add the one you want.

**Claude** on the web, desktop or mobile: open **Customize > Connectors**, click **+ Add**, then **Add custom connector**, name it `Stophy`, paste `https://mcp.stophy.dev/mcp` and continue. Claude opens stophy.dev to approve. Turn Stophy on per chat under **+ > Connectors**. The Free plan allows one custom connector. **Grok:** open [grok.com/connectors](https://grok.com/connectors), click **New Connector**, then **Custom**, paste the URL and sign in.

## Use an API key

Keep the key in `STOPHY_API_KEY`, never in a file you commit. [Get credentials](https://docs.stophy.dev/get-credentials.md) has every way to get one.

| Client | Add to the `https://api.stophy.dev/mcp` setup |
| - | - |
| Claude Code | `--header "Authorization: Bearer $STOPHY_API_KEY"`. Add `--scope user` for every project. |
| Codex | `--bearer-token-env-var STOPHY_API_KEY`. Codex reads it at start, so it is never saved to `~/.codex/config.toml`. |
| OpenCode | `--header 'Authorization=Bearer {env:STOPHY_API_KEY}'` |
| Cursor | `"headers": { "Authorization": "Bearer ${env:STOPHY_API_KEY}" }` under `stophy` |
| VS Code | In `.vscode/mcp.json`, add an input `{ "type": "promptString", "id": "stophy-key", "description": "Stophy API key", "password": true }`. Under `servers.stophy` set `"type": "http"`, the `url` and `"headers": { "Authorization": "Bearer ${input:stophy-key}" }`. |

The server refuses a wrong key. An agent with no key can call `stophy_signup`, which returns a link for you to approve and a code, then the key when called again with the code. See [Sign up from an agent](https://docs.stophy.dev/get-credentials.md#sign-up-from-an-agent).

## Tools

With sign-in or a key, the server lists a tool for each product. Without a key it lists only `stophy_search`, `stophy_scrape`, `stophy_map`, `stophy_parse` and `stophy_signup`. A call costs what it does over HTTP, and `costUsd` in a result is what it cost. See [Pricing](https://docs.stophy.dev/account/pricing.md).

| Tools | What they do |
| - | - |
| `stophy_crawl`, `stophy_crawl_status`, `stophy_crawl_cancel` | Start a background crawl, read its pages, stop it |
| `stophy_extract` | Pull fields you name from pages as JSON |
| `stophy_agent`, `stophy_agent_status`, `stophy_agent_cancel` | Start a task that searches and reads pages, read its answer, stop it |
| `stophy_developer_search` | Search code docs, issues, pull requests and releases |
| `stophy_paper_search`, `stophy_paper_read`, `stophy_paper_similar` | Search research papers, read one, find similar ones |
| `stophy_monitor`, `stophy_monitor_read` | Create, change, run or delete a monitor with `action`; read monitors, their checks and what changed |
| `stophy_browser_open`, `stophy_browser_run`, `stophy_browser_close` and three more | Drive a cloud browser |

Ask *"What are people saying about Bun on Reddit?"* and the agent calls `stophy_scrape` with a Reddit search URL and `"formats": [{ "type": "json", "parser": "reddit-search" }]`. See [Pre-built parsers](https://docs.stophy.dev/scrape/prebuilt-parsers).

A tool's description names the inputs its schema leaves out, such as `profile` on `stophy_scrape`. They work as over HTTP. Page Markdown and HTML come back as their own text blocks after the JSON, which keeps `[text block 2]` in their place. Over MCP, `stophy_scrape` keeps link text and drops link addresses: send `"linkStyle": "inline"` for `[text](address)`, or add `links` to `formats`.

## Drive a browser

| Tool | What it does |
| - | - |
| `stophy_browser_open` | Opens a cloud browser. Returns its `id`, `expiresAt` and a live view link you can watch or take over. With `url`, it also returns the page's elements with refs such as `e12`. Takes `url`, `profile`, `proxy`, `location`, `ttl` and `captureConsole`, and the other session options of [Browser sessions](https://docs.stophy.dev/browser/overview), such as `solveCaptchas`. It opens `direct` unless you send `proxy` or `location`. |
| `stophy_browser_run` | Does one thing. Send the `id` and exactly one of `steps`, `code` or `prompt`. |
| `stophy_browser_close` | Closes the browser, saves its profile, and bills the session. Returns the time, traffic and cost. |

`stophy_browser_upload` puts a file in an open browser. `stophy_browser_task` gives a goal to an agent that clicks through a public site and answers, as in [Browser tasks](https://docs.stophy.dev/browser/tasks.md), and `stophy_browser_task_cancel` stops it.

`steps` is up to 50 actions that run in order and stop at the first failure. The actions are `open`, `back`, `reload`, `snapshot`, `click`, `dblclick`, `hover`, `check`, `uncheck`, `fill`, `type`, `press`, `select`, `scroll`, `drag`, `find`, `wait`, `get`, `is`, `read`, `screenshot`, `pdf`, `tab`, `dialog`, `upload`, `network` and `console`. A step names an element by its ref from the latest page, and `find` picks one by role and name. Steps that can change the page answer with the page as its own text block. `read`, `screenshot`, `pdf`, `get`, `is`, `network` and `console` only look, so a call of only those leaves the page out; `snapshot` asks for it. `read` returns Markdown, `network` lists requests since the session opened, and `console` needs `captureConsole`.

`code` is JavaScript by default, with `page` a Playwright Page. Send statements, whose last expression or `return` value comes back as `result`, or a function such as `async (page) => { ... }`. With `"language": "python"`, `page` is in scope and you set `result`. `prompt` is plain words for an agent. A call may take 30 seconds, and `timeout` raises that to 300.

A session is billed from `stophy_browser_open` to `stophy_browser_close`, so tell your agent to close every browser it opens. The tools were named `browserOpen`, `browserRun` and so on until November 2026, and those names still work.

## More tools and a local server

`?toolsets=web` on `https://api.stophy.dev/mcp` adds batches and more crawl and agent tools, such as `batchScrape`, `crawlList` and `agentList`. `toolsets=browser` adds `stophy_browser_downloads`, `stophy_browser_recording`, `stophy_browser_proxy`, `stophy_browser_extensions`, `stophy_browser_network_policy`, `browserProfiles` and `browserTaskStatus`. `toolsets=webhook` adds the webhook delivery tools.

For an app that can only start a local server, `npx -y @stophy/mcp` (Node.js 18 or later) passes every request to the hosted server. Set `STOPHY_API_KEY` for every tool, and `STOPHY_MCP_URL` to change the server. Claude Desktop uses the connector above, not this package.

## Check it

Ask your agent to search YouTube for `rust tutorial` and summarize the top three videos. If `stophy` shows no tools, restart your client.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.