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

Serving several agents

A client that starts the server itself gets a process of its own, which is what stdio is for. A self-hosted agent is often not that: there are several of them, they come and go, and they run where no parent process can start one. Run the server once instead and let them connect over HTTP. Stdio remains the default and is unchanged.

Start it#

npx -y @zactonz/mcp --http

It listens on http://127.0.0.1:8808/mcp, loopback only, and speaks MCP's streamable HTTP transport. Put the keys the process should use in ZACTONZ_API_KEYS before starting it, or have each caller bring its own as described below.

Point a client at that URL as a remote MCP server. For Claude Code:

claude mcp add --transport http zactonz http://127.0.0.1:8808/mcp

Keys per request#

A request may bring its own keys, in the x-zactonz-api-keys header or as a bearer token:

curl -sS http://127.0.0.1:8808/mcp -H 'x-zactonz-api-keys: zk_qr_…' -H 'accept: application/json, text/event-stream' -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Those keys are used for that request and no other: the tools the caller is offered, and the quota a call spends, follow the key in the header. So two agents holding different keys can share one process without seeing each other's tools or spending each other's quota.

A request that brings no keys is answered with the keys in ZACTONZ_API_KEYS. Set ZACTONZ_MCP_REQUIRE_KEY_HEADER=1 to refuse it instead, and make every caller bring its own.

With Claude Code the header goes on the server entry:

claude mcp add --transport http zactonz http://127.0.0.1:8808/mcp --header "x-zactonz-api-keys: zk_qr_…"

Health probe#

GET /healthz answers a liveness probe for a container or an orchestrator. It reports the version, how many API-backed tools the build carries, how many keys the process holds, never which products they are for, and what the process is currently sending to the API: calls in flight, calls waiting, and how long a pause has left. The tool count is the build's catalogue, not what a caller will be offered, which depends on the keys it brings. It makes no request to the API and spends nothing.

In a container#

Inside a container the server has to bind every interface to be reachable through a port mapping, which means setting ZACTONZ_MCP_HOST=0.0.0.0 and publishing port 8808.

Binding away from loopback makes the server reachable from outside the machine, and it has no authentication of its own: a caller is whoever holds a Zactonz key. The server says as much on stderr when it starts. Put TLS in front of it, name the hosts it should answer to in ZACTONZ_MCP_ALLOWED_HOSTS, and consider requiring the key header.

What it does not keep#

Nothing is remembered between requests. Each one is answered by a server built around that request's keys and discarded with it, which is what keeps the keys from reaching the next caller. There is no session, so GET /mcp and DELETE /mcp answer 405: this server has nothing to stream and nothing to end. Requests beyond ZACTONZ_MCP_MAX_REQUESTS at once are refused with a 503 and a Retry-After rather than queued.

Holding back a fleet's traffic#

One cap on outbound calls covers the whole process, not each request, since that is the only place a fleet's traffic can be held back. The process sends at most ZACTONZ_MCP_MAX_CONCURRENCY calls to the API at once, eight by default, and queues the rest. See Security & limits for why the cap exists and for the pause that follows a run of unanswered calls.

Configuration#

These apply only when the server is listening over HTTP. The variables on the Setup tab apply in both modes.

Variable Purpose Default
ZACTONZ_MCP_TRANSPORT stdio or http; the same as --http stdio
ZACTONZ_MCP_HOST Address to bind; the same as --host 127.0.0.1
ZACTONZ_MCP_PORT Port to bind; the same as --port. 0 takes any free port 8808
ZACTONZ_MCP_REQUIRE_KEY_HEADER 1 refuses a request that brings no key of its own off
ZACTONZ_MCP_ALLOWED_HOSTS Host header values to answer to, separated by commas loopback
ZACTONZ_MCP_ALLOWED_ORIGINS Browser origins allowed to call, separated by commas none
ZACTONZ_MCP_MAX_REQUESTS Requests handled at once before load is shed. 0 for no limit 64
ZACTONZ_MCP_MAX_BODY_BYTES Largest request body accepted 1048576

Troubleshooting#

  • 403. The request carried an Origin header, or a Host header naming something the server was not given. The reason, with the value, is on stderr. Name the host in ZACTONZ_MCP_ALLOWED_HOSTS, or the origin in ZACTONZ_MCP_ALLOWED_ORIGINS if a browser really should reach it.
  • 401 with keys in the header. None of the values presented is a Zactonz key, which looks like zk_<product>_<secret>. A request that brings no key at all is answered with ZACTONZ_API_KEYS instead, unless ZACTONZ_MCP_REQUIRE_KEY_HEADER=1.
  • 406 when calling with curl. The Accept header has to list both application/json and text/event-stream.
  • 405 on GET /mcp. Expected: the server keeps no session, so there is no stream to open. Send POST.
  • Calls are slower under load. They are queued behind ZACTONZ_MCP_MAX_CONCURRENCY. GET /healthz reports how many are in flight and how many are waiting.