# Hand off to AI

> Hand your AI coding assistant one file to integrate ZeroCaptcha: the brief, its JSON, Claude Code, Cursor, AGENTS.md and Copilot files, and an MCP server.

Source: https://zerocaptcha.io/docs/ai

Working with an AI coding assistant? Hand it one file and it has everything it needs to integrate
ZeroCaptcha on the first try: the API's address, how to authenticate with a key read from the
environment, every task type's request and reply, polling and callbacks, every error code and what
to do about it, the retry rules, a tested reference client in Node, Python, Go and bash, and a
checklist it works through before it says it is done.

Every file is written when this site is built, from the API's own OpenAPI contract and the tested
reference clients, and names the API at `https://api.zerocaptcha.io`. None of them contains a key.

## The files

- [Integration brief](https://zerocaptcha.io/ai/integration.md): one self-contained file: configuration, every call, polling and callbacks, every error code, retries, reference clients in four languages and a checklist.
- [The brief as JSON](https://zerocaptcha.io/ai/zerocaptcha.json): endpoints, fields, enums, errors, rules and examples, for tools.
- [Claude Code skill](https://zerocaptcha.io/ai/claude/SKILL.md): save as .claude/skills/zerocaptcha/SKILL.md in your project.
- [Cursor rule](https://zerocaptcha.io/ai/cursor/zerocaptcha.mdc): save as .cursor/rules/zerocaptcha.mdc in your project.
- [AGENTS.md section](https://zerocaptcha.io/ai/AGENTS.md): paste into your project's AGENTS.md, read by Codex, Jules, Gemini CLI and other agents.
- [GitHub Copilot instructions](https://zerocaptcha.io/ai/copilot-instructions.md): save as .github/copilot-instructions.md in your repository.

Start with the integration brief. The other files carry the same rules in the form each assistant
reads on its own, so it follows them whenever it touches your ZeroCaptcha code:

- **Claude Code:** save the skill as `.claude/skills/zerocaptcha/SKILL.md` in your project.
- **Cursor:** save the rule as `.cursor/rules/zerocaptcha.mdc`.
- **Codex, Jules, Gemini CLI and other agents that read AGENTS.md:** paste the section into your
  project's `AGENTS.md`.
- **GitHub Copilot:** save the instructions as `.github/copilot-instructions.md`, or add them to it.

In the dashboard, **Hand off to AI** on the API keys page downloads the integration brief with your
account's API address filled in. It never includes your key: give your assistant the key through
your environment or secret store, as the brief tells it to, never by pasting it into a chat.

> **Your key stays yours**
>
> The brief tells an assistant to read the key from `ZEROCAPTCHA_KEY` and never to write it into code,
> logs or chat. Don't paste a key into an AI chat: anyone who has it can spend your balance.

## A prompt that works

```text
Read https://your-docs-site/ai/integration.md and integrate ZeroCaptcha into this project to solve
the Turnstile widget on <page>. Read the API key from the ZEROCAPTCHA_KEY environment variable.
Work through the brief's checklist before you finish.
```

Replace the address with this site's, as the [integration brief](https://zerocaptcha.io/ai/integration.md) link shows.

## Every page, for assistants

- **On every docs page,** the buttons at the top copy the page as Markdown, open its Markdown, or
  open Claude or ChatGPT with a prompt that carries the page's Markdown address.
- **[/llms.txt](https://zerocaptcha.io/llms.txt)** lists every docs page's Markdown and the files above, in the
  [llms.txt](https://llmstxt.org) format.
- **[/llms-full.txt](https://zerocaptcha.io/llms-full.txt)** is every docs page as Markdown in one file, followed by the
  integration brief.
- **[/openapi.json](https://zerocaptcha.io/openapi.json)** is the API's OpenAPI 3.1 contract, for code generators and API
  tools.

## The MCP server

The ZeroCaptcha MCP server lets an assistant that speaks the Model Context Protocol (Claude Code,
Claude Desktop, Cursor and others) call ZeroCaptcha itself, over stdio, with your key from its
environment:

| Tool | What it does |
| --- | --- |
| `create_task` | Creates a Cloudflare Turnstile task, or a challenge page's task through your proxy, and, unless told not to, waits for its token or clearance. Charged if it succeeds. |
| `get_task_result` | Reads a task: its status, cost, and token while it is valid. |
| `get_balance` | Reads the available and held balance. |
| `search_docs` | Searches these docs, from `/llms-full.txt`, and returns the best sections with their links. |

It needs Node.js 20 or later and three settings: `ZEROCAPTCHA_KEY`, your API key; `ZEROCAPTCHA_API`,
the API's address, `https://api.zerocaptcha.io` when unset; and `ZEROCAPTCHA_DOCS`, this site's
address, `https://zerocaptcha.io` when unset, for `search_docs`. In Claude Code:

```sh
claude mcp add zerocaptcha --env ZEROCAPTCHA_KEY=$ZEROCAPTCHA_KEY \
  --env ZEROCAPTCHA_API=$ZEROCAPTCHA_API --env ZEROCAPTCHA_DOCS=$ZEROCAPTCHA_DOCS \
  -- node /path/to/zerocaptcha-mcp/dist/main.js
```

In Cursor, `.cursor/mcp.json`, and in most other clients the same shape:

```json
{
  "mcpServers": {
    "zerocaptcha": {
      "command": "node",
      "args": ["/path/to/zerocaptcha-mcp/dist/main.js"],
      "env": {
        "ZEROCAPTCHA_API": "https://api.zerocaptcha.io",
        "ZEROCAPTCHA_DOCS": "https://zerocaptcha.io"
      }
    }
  }
}
```

The server reads `ZEROCAPTCHA_KEY` from its environment. Start your client with it set; if your
client does not pass its environment on, add it to `env` only in a config file you keep out of
version control.

Every task the server creates is real and charged if it succeeds, so give it a key with a daily
[spend cap](https://zerocaptcha.io/docs/keys#cap-a-keys-daily-spend). It is not in a package registry yet (coming). Until it
is, give your assistant the [integration brief](https://zerocaptcha.io/ai/integration.md), which covers every call the
server makes, or call the API over plain HTTP as the [quickstart](https://zerocaptcha.io/docs/quickstart) does.