# Zactonz MCP Server: Setup

> A Model Context Protocol server that gives AI assistants the Zactonz APIs as tools: screenshots, page to Markdown, link previews, DNS, SSL, WHOIS, email checks, QR codes, barcodes, social images, image conversion and translation.

Page: https://developers.zactonz.com/tools/zactonz-mcp/setup/

Complete documentation for this product: https://developers.zactonz.com/tools/zactonz-mcp.md

## 1. Create API keys

Create a key for each product you want the assistant to use in the [API console](https://developers.zactonz.com/console/). A key works for one product, and the product is part of the key: `zk_screen_…` is a screenshot key, `zk_markdown_…` a Markdown key. Put every key you have in `ZACTONZ_API_KEYS`, separated by commas. The server uses the right one for each call and offers the assistant only the tools those keys can call.

## 2. Add the server to your client

The server is published on npm as [@zactonz/mcp](https://www.npmjs.com/package/@zactonz/mcp) and is run with `npx`, so there is nothing to install by hand.

Clients that read an `mcpServers` block, such as Claude Desktop, Cursor and Windsurf:

```json
{
  "mcpServers": {
    "zactonz": {
      "command": "npx",
      "args": ["-y", "@zactonz/mcp"],
      "env": {
        "ZACTONZ_API_KEYS": "zk_screen_…,zk_markdown_…,zk_domain_…"
      }
    }
  }
}
```

VS Code, in `.vscode/mcp.json`:

```json
{
  "servers": {
    "zactonz": {
      "command": "npx",
      "args": ["-y", "@zactonz/mcp"],
      "env": { "ZACTONZ_API_KEYS": "zk_screen_…,zk_markdown_…" }
    }
  }
}
```

Claude Code:

```bash
claude mcp add zactonz --env ZACTONZ_API_KEYS="zk_screen_…,zk_markdown_…" -- npx -y @zactonz/mcp
```

On Windows, if the client cannot start `npx` directly, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@zactonz/mcp"]`.

The first start downloads the package and its two dependencies; later starts are immediate. To pin a commit or run without a registry, the repository's README describes running from source.

## 3. Check it works

Ask the assistant to run `check_api_key`. It reports the plan and the quota remaining for each key. Without any valid key the server still starts and lists every tool, and each call answers with these setup instructions.

## Configuration

| Variable | Purpose | Default |
|---|---|---|
| `ZACTONZ_API_KEYS` | API keys, separated by commas | none |
| `ZACTONZ_MCP_INLINE_IMAGE_BYTES` | Largest image returned inline, in bytes. `0` returns links only | `750000` |
| `ZACTONZ_BASE_URL` | API base URL | `https://api.zactonz.com` |

Values in `ZACTONZ_API_KEYS` that are not Zactonz keys are ignored and reported on stderr, with the value masked, rather than guessed at.

## Troubleshooting

- **A tool is missing.** Only tools with a key are listed. Add a key for that product and restart the client.
- **Every call answers with setup instructions.** `ZACTONZ_API_KEYS` is empty or holds no valid key. The server prints the reason on stderr, which most clients show in their MCP log.
- **"Missing or invalid API key."** The key was revoked or mistyped. Ask the assistant to run `check_api_key`, or check the key in the console.
- **A screenshot has no inline image.** The file is over the inline limit. Lower the quality or size, or raise `ZACTONZ_MCP_INLINE_IMAGE_BYTES`.