# @captchala/mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for [CaptchaLa](https://captcha.la). It lets MCP clients such as **Claude Desktop**, **Cursor**, and others search the CaptchaLa documentation and validate or issue CaptchaLa tokens directly from your assistant.

The server speaks MCP over **stdio** transport.

## Tools

| Tool | Description | Credentials |
| --- | --- | --- |
| `search_captchala_docs` | Search the CaptchaLa docs and return the most relevant sections for a query. | Not required |
| `get_captchala_doc` | Fetch a specific documentation page by path (e.g. `getting-started`). | Not required |
| `validate_captcha_token` | Validate a pass token against the CaptchaLa API. | App Key + Secret |
| `issue_server_token` | Issue a server-side challenge token for an action. | App Key + Secret |

The documentation tools work without any credentials. The `validate_captcha_token` and `issue_server_token` tools require a CaptchaLa **App Key** and **App Secret**, supplied either per call (as tool arguments) or via the `CAPTCHALA_APP_KEY` and `CAPTCHALA_APP_SECRET` environment variables.

## Install

Install globally:

```bash
npm install -g @captchala/mcp
```

Or run on demand with `npx`:

```bash
npx @captchala/mcp
```

## Claude Desktop configuration

Add the server to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "captchala": {
      "command": "npx",
      "args": ["-y", "@captchala/mcp"],
      "env": {
        "CAPTCHALA_APP_KEY": "your-app-key",
        "CAPTCHALA_APP_SECRET": "your-app-secret"
      }
    }
  }
}
```

If you only need the documentation tools, you can omit the `env` block.

## Cursor

Cursor supports MCP servers as well. Add the same `command`/`args`/`env` entry under Cursor's MCP settings (Settings → MCP → Add server). The stdio transport is used automatically.

## Example prompts

- "Search the CaptchaLa docs for how server-side validation works."
- "Fetch the CaptchaLa getting-started doc."
- "Validate this CaptchaLa pass token: `<token>` for client IP 1.2.3.4."
- "Issue a CaptchaLa server token for the `login` action."

## Environment variables

| Variable | Purpose |
| --- | --- |
| `CAPTCHALA_APP_KEY` | Your CaptchaLa App Key (sent as `X-App-Key`). |
| `CAPTCHALA_APP_SECRET` | Your CaptchaLa App Secret (sent as `X-App-Secret`). |

## License

MIT © CaptchaLa &lt;supply@captcha.la&gt;