Zactonz MCP Server

v0.3.0

A Model Context Protocol server that gives AI assistants and agent fleets the Zactonz APIs as tools, over stdio or HTTP, with structured results: screenshots, page to Markdown, link previews, DNS, SSL, WHOIS, email checks, QR codes, barcodes, social images, image conversion and translation.

Node.js 20+An MCP client over stdio or HTTPZactonz API keys Updated 17 Nov 2026

Setup

1. Create API keys#

Create a key for each product you want the assistant to use in the API 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 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:

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

VS Code, in .vscode/mcp.json:

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

Claude Code:

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.

These configurations start one server per client over stdio. To run the server once and let several agents connect to it over HTTP, see Serving several agents.

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_MCP_MAX_CONCURRENCY API calls in flight at once. 0 for no limit 8
ZACTONZ_MCP_BREAKER_FAILURES Unanswered calls before the server pauses for 30 seconds. 0 to never 5
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.
  • "The Zactonz API has failed to answer several calls in a row." The server has paused and says how long is left. It resumes by itself, one call at a time. If the API is fine and this is firing, raise ZACTONZ_MCP_BREAKER_FAILURES or set it to 0.