Hand off to 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 (/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 (/ai/zerocaptcha.json): endpoints, fields, enums, errors, rules and examples, for tools.
• Claude Code skill (/ai/claude/SKILL.md): save as .claude/skills/zerocaptcha/SKILL.md in your project.
• Cursor rule (/ai/cursor/zerocaptcha.mdc): save as .cursor/rules/zerocaptcha.mdc in your project.
• AGENTS.md section (/ai/AGENTS.md): paste into your project's AGENTS.md, read by Codex, Jules, Gemini CLI and other agents.
• GitHub Copilot instructions (/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

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 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 lists every docs page’s Markdown and the files above, in the llms.txt format.
• /llms-full.txt is every docs page as Markdown in one file, followed by the integration brief.
• /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:

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:

{
  "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. It is not in a package registry yet (coming). Until it is, give your assistant the integration brief, which covers every call the server makes, or call the API over plain HTTP as the quickstart does.