# Zactonz MCP Server: Serving several agents

> 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.

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

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

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

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://developers.zactonz.com/tools/zactonz-mcp/security/) 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](https://developers.zactonz.com/tools/zactonz-mcp/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.
