# Clawifi docs

> Connect an AI agent to Clawifi in four steps, MCP first: get a key, install, add it to Claude Code, Codex, Cursor or any MCP client, and make the first call.

Canonical page: https://clawifi.dev/docs

## Quickstart

### 1. Get a key

Create an account at /signup. The Free plan includes 1,000 credits a month. Verify your email, then copy the API key the console shows you. It is shown once.

```
https://clawifi.dev/signup
```

### 2. Install

One package installs the MCP server (clawifi-mcp) and the CLI. It needs Python 3.11 or newer.

```sh
pip install clawifi
```

### 3. Add to your client

Add Clawifi to your agent with your key. Choose your client below; each line is all it needs.

**Claude Code**

```sh
claude mcp add clawifi -e CLAWIFI_API_KEY=your_key -- clawifi-mcp
```

**Codex**

```sh
codex mcp add clawifi --env CLAWIFI_API_KEY=your_key -- clawifi-mcp
```

**Cursor**

```json
{ "mcpServers": { "clawifi": { "command": "clawifi-mcp", "env": { "CLAWIFI_API_KEY": "your_key" } } } }
```

Paste into ~/.cursor/mcp.json (or the project's .cursor/mcp.json).

**Claude Desktop**

```json
{ "mcpServers": { "clawifi": { "command": "clawifi-mcp", "env": { "CLAWIFI_API_KEY": "your_key" } } } }
```

Paste into claude_desktop_config.json (Settings, Developer, Edit config), then restart Claude Desktop.

**Hermes**

```sh
CLAWIFI_API_KEY=your_key clawifi mcp config
```

Add it to Hermes's MCP servers: the command prints the block; put your key in its CLAWIFI_API_KEY.

**Any MCP client**

```sh
CLAWIFI_API_KEY=your_key clawifi mcp config
```

For any client that speaks MCP over stdio: the command prints the block; put your key in its CLAWIFI_API_KEY.

### 4. First call

Ask your agent to search or read a page (for example "search the web for the Model Context Protocol spec"), or check the key from a terminal first.

```sh
CLAWIFI_API_KEY=your_key clawifi quicktest --url https://example.com
```

## Remote MCP

No install: point your client at https://api.clawifi.dev/mcp (streamable HTTP) and send your key as Authorization: Bearer, or in X-Clawifi-Api-Key. Every tool call is billed exactly like the REST route it runs. OAuth is not offered; use an API key. api.clawifi.qzz.io keeps working for older clients.

**Claude Code**

```sh
claude mcp add --transport http clawifi https://api.clawifi.dev/mcp \
  --header "Authorization: Bearer $CLAWIFI_API_KEY"
```

**Cursor**

```json
{ "mcpServers": { "clawifi": { "url": "https://api.clawifi.dev/mcp", "headers": { "Authorization": "Bearer ${env:CLAWIFI_API_KEY}" } } } }
```

Paste into ~/.cursor/mcp.json; Cursor reads CLAWIFI_API_KEY from your environment.

**Codex**

```toml
[mcp_servers.clawifi]
url = "https://api.clawifi.dev/mcp"
bearer_token_env_var = "CLAWIFI_API_KEY"
```

Add to your Codex config.toml; Codex sends CLAWIFI_API_KEY as the bearer token.

Tools: fetch_url, scrape_url, extract_url, search_free, map_site, start_crawl, get_crawl, create_job, get_job, list_history, list_monitors, estimate, account and credits.

Without a key, search_free, fetch_url, scrape_url (with passages) and map_site still work as a trial: 12 calls a minute and 50 a day per address, with the playground's caps. Past that the tool answers with a link to get a free key at https://clawifi.dev/signup.

## Python SDK

The same package, pip install clawifi, is the Python SDK. It calls the same API with the same key and reads CLAWIFI_API_KEY from the environment.

```sh
pip install clawifi
```

```python
from clawifi import Clawifi

client = Clawifi()
page = client.fetch("https://example.com")
results = client.search_free("Model Context Protocol")
print(client.credits())
```

## HTTP

Calls are JSON over HTTPS with your key as a bearer token. Work is mostly POST (fetch, search, scrape, crawl); reads such as GET /history and GET /account/me are GET. Billable answers carry X-Clawifi-Credits-Charged and X-Clawifi-Credits-Remaining. Add "dry_run": true to any paid call to see what it would cost first: its minimum, its maximum where there is one, what raises the price, your balance and whether it would be refused. Nothing runs and nothing is charged. The API is at https://api.clawifi.dev; api.clawifi.qzz.io keeps working for older clients.

```sh
curl https://api.clawifi.dev/fetch \
  -H "Authorization: Bearer $CLAWIFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
```

## Hosted browser render

Renders JavaScript-heavy pages in a hosted browser. It does not bypass bot protection or CAPTCHAs. Pro and Scale plans only: 6 credits per started browser-minute, at least 6, up to 500 minutes a month on Pro and 2,500 on Scale. Modes: markdown, content (HTML), links and scrape (CSS selectors).

```sh
curl https://api.clawifi.dev/browse/cloud \
  -H "Authorization: Bearer $CLAWIFI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","mode":"markdown"}'
```

## Errors

Every error answers with a status and an error object (code, message, retryable); most also carry a detail sentence.

- **401 Unauthorized:** The key or session is missing, wrong or expired ("Invalid API key", "API key has expired"). Create a new key in the console.
- **402 Not enough credits:** The balance does not cover the call's minimum. The message names both: "Insufficient Clawifi credits: needed 6, balance 2". Nothing is charged. Send the same call with "dry_run": true to check before you run it.
- **403 Account suspended:** The account is suspended while a payment dispute is open. Keys stop working; you can still sign in and read the console. Email clawifisupport@rearclabs.com.
- **403 plan_required:** The feature needs a higher plan, for example hosted browser render (Pro or Scale) or brute-force subdomains (any paid plan). error.code is plan_required.
- **409 Conflict:** Something already exists or changed: a second plan checkout ("you already have a plan, change it instead"), a plan change that cannot apply yet, or an email that already has an account.
- **429 Too many requests:** Too many calls at once for your plan, or a monthly cap (hosted render minutes) is used up. Wait the seconds in the Retry-After header and retry; a monthly cap says when it resets.

## Credits per operation

The same table the API charges from (`GET /billing/manifest`). A call needs its minimum in balance to start and is charged what it actually cost; cache hits and failed calls cost 0.

| Operation | Credits | Per | Notes |
| --- | --- | --- | --- |
| search | 1 | call | search, plain fetch/scrape, article extract, package/dataset/code/archive/academic lookup, single OSINT lookup, social reads |
| browser_render | 3 | call | browser render, or a fetch/scrape that escalates to the browser; a Reddit thread the browser could not open and the Wayback Machine copy answered counts as rendered (the renders ran), while a page reached in the archive without a render costs the base call |
| pdf | 2 | started 50 pages | in place of the base call: 2 for 1-50 pages, 4 for 51-100 |
| llm_extract | 4 | call | an extract that runs a language model; hosted extraction is deterministic today |
| map | 1 | started 10 URLs returned | at least 1 |
| crawl | 1 | page | +2 per page that needed JS rendering; at least 1 |
| monitor_check | 1 | check | 3 with the browser |
| osint_recon_bundle | 5 | call | domain recon, email recon, username sweep |
| research | 30 | call | 5 per source searched + 10 per page read, at least 30, at most 300 |
| research_plan | 5 | call |  |
| cloud_render | 6 | started browser-minute | Pro and Scale plans (500 and 2,500 minutes a month); at least 6. Renders JavaScript-heavy pages in a hosted browser. It does not bypass bot protection or CAPTCHAs. |
| passages | 0 | call | query/top_k on fetch, scrape and browse add nothing |
| playground | 0 | call |  |