# MCP server

> Connect Claude Code, Claude Desktop, Cursor, OpenClaw, Hermes or any MCP client to the Solvecha remote MCP server and give your agent captcha-solving tools.

The Solvecha MCP server is a remote server. There is nothing to install. It uses the Streamable HTTP transport and your normal API key.

```
https://api.solvecha.com/mcp
```

Send the key in the header `Authorization: Bearer YOUR_API_KEY`. The server has no login page and no OAuth. Listing the tools needs no key. Calling a tool does.

## Tools

| Tool | What it does |
|---|---|
| `solve_recaptcha_grid` | Solves a reCAPTCHA v2 image challenge. Input: `task` (the instruction text), `grid` (`3x3`, `4x4` or `1x1`), `images` (base64 or https URLs). Returns `selected_tiles` (counted from 1, left to right, top to bottom) and `positions` such as `row 1, column 3`. |
| `solve_text_captcha` | Reads a picture with distorted text. Returns `text`. |
| `solve_geetest_slider` | Solves a GeeTest slider. Returns `offset_percent` of the background width. |
| `solve_funcaptcha` | Solves a FunCAPTCHA tile puzzle (`mode: tile`) or match puzzle (`mode: match`). Returns `selected_tiles`. |
| `get_account_status` | Shows plan, solves left today, balance and the time to the daily reset. Free. |
| `report_result` | Tells us whether Google accepted or rejected a reCAPTCHA answer (`job_id`, `verdict`, `grid`). Free. |

The solve tools wait for the answer, usually 2 to 6 seconds. `timeout_seconds` (5 to 90, default 45) sets the longest wait.

## Images

Send each picture as base64 (a `data:` URL is fine) or as an `https` URL. For URLs the server follows these rules:

- Only `https` on port 443. No user name or password in the URL.
- Addresses in private or reserved ranges are refused, also after a redirect.
- At most 3 redirects, 10 seconds, 2 MB per picture and 3 MB per call.
- The data must be a picture (PNG, JPEG, GIF, WebP or BMP).


> **Note:**
> A model has to write base64 text into the tool call, one character after the other. A 240x240 JPEG of a 3x3 grid is about 12 KB and 16,000 characters, which costs time and tokens. Prefer an `https` URL of the picture, a small JPEG of only the grid, or the [browser extension](https://solvecha.com/docs/browser-extension.md), which needs no tool call.


## Billing and limits

The tools call the same API as the REST endpoints. The key check, the rate limits, the daily quota, the balance and the charge are the same. You pay for a successful solve once. See [Rate limits](https://solvecha.com/docs/rate-limits.md) and [Plans and billing](https://solvecha.com/docs/plans-and-billing.md).

When something is wrong, the tool returns an error text that tells the agent what to do. For example it names the API error code (`15` wrong key, `16` out of credit, `11` rate limit).

## Connect a client


**Claude Code**

```bash
claude mcp add --transport http solvecha https://api.solvecha.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

**Claude Code (.mcp.json)**

```json
{
  "mcpServers": {
    "solvecha": {
      "type": "http",
      "url": "https://api.solvecha.com/mcp",
      "headers": { "Authorization": "Bearer ${SOLVECHA_API_KEY}" }
    }
  }
}
```

**Cursor (~/.cursor/mcp.json)**

```json
{
  "mcpServers": {
    "solvecha": {
      "url": "https://api.solvecha.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SOLVECHA_API_KEY}" }
    }
  }
}
```

**VS Code (.vscode/mcp.json)**

```json
{
  "inputs": [
    { "type": "promptString", "id": "solvecha-key", "description": "Solvecha API key", "password": true }
  ],
  "servers": {
    "solvecha": {
      "type": "http",
      "url": "https://api.solvecha.com/mcp",
      "headers": { "Authorization": "Bearer ${input:solvecha-key}" }
    }
  }
}
```

**Claude Desktop (mcp-remote)**

```json
{
  "mcpServers": {
    "solvecha": {
      "command": "npx",
      "args": ["mcp-remote", "https://api.solvecha.com/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" }
    }
  }
}
```

**OpenClaw (openclaw.json)**

```json
{
  mcp: {
    servers: {
      solvecha: {
        url: "https://api.solvecha.com/mcp",
        transport: "streamable-http",
        headers: { Authorization: "Bearer ${SOLVECHA_API_KEY}" }
      }
    }
  }
}
```

**Hermes (~/.hermes/config.yaml)**

```yaml
mcp_servers:
  solvecha:
    url: "https://api.solvecha.com/mcp"
    headers:
      Authorization: "Bearer ${SOLVECHA_API_KEY}"
```


Replace `YOUR_API_KEY` with your key, or set `SOLVECHA_API_KEY` in the environment. Do not commit the key to a repository.

- **Claude Desktop:** the `mcp-remote` entry runs a small local bridge (`npx mcp-remote`). The space inside the env value is on purpose: on Windows, spaces in `args` are not escaped. You can also add a custom connector in the Claude settings and fill its request headers with `Authorization: Bearer YOUR_API_KEY`.
- **OpenClaw:** set `transport` to `streamable-http`, because the default is `sse`. You can also add the server with `openclaw mcp add solvecha --url https://api.solvecha.com/mcp --transport streamable-http --header ...`. Run `openclaw mcp add --help` for the header syntax of your version.
- **Hermes:** run `/reload-mcp` in a running session after you edit the file.
- **Other clients:** any client that supports the Streamable HTTP transport with a custom header works. Cline needs `"type": "streamableHttp"`. Zed uses `context_servers` with `url` and `headers`.

## Test the connection

Use the MCP Inspector in command-line mode:

```bash
npx @modelcontextprotocol/inspector --cli https://api.solvecha.com/mcp --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" --method tools/list
```

Or call the endpoint by hand:

```bash
curl -s https://api.solvecha.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account_status","arguments":{}}}'
```

## Notes for operators

- The server is stateless and answers with plain JSON, so proxies do not have to keep a stream open. `GET` and `DELETE` on `/mcp` answer `405`.
- A tool call that waits for a solve is one HTTP request of up to 90 seconds.
- Agents that open a visible browser can use the [browser extension](https://solvecha.com/docs/browser-extension.md) instead. It needs no tool calls.