Zactonz MCP Server
v0.3.0A 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.
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 anOriginheader, or aHostheader naming something the server was not given. The reason, with the value, is on stderr. Name the host inZACTONZ_MCP_ALLOWED_HOSTS, or the origin inZACTONZ_MCP_ALLOWED_ORIGINSif a browser really should reach it.401with keys in the header. None of the values presented is a Zactonz key, which looks likezk_<product>_<secret>. A request that brings no key at all is answered withZACTONZ_API_KEYSinstead, unlessZACTONZ_MCP_REQUIRE_KEY_HEADER=1.406when calling with curl. TheAcceptheader has to list bothapplication/jsonandtext/event-stream.405onGET /mcp. Expected: the server keeps no session, so there is no stream to open. SendPOST.- Calls are slower under load. They are queued behind
ZACTONZ_MCP_MAX_CONCURRENCY.GET /healthzreports how many are in flight and how many are waiting.