Get started

Authentication

In stdio mode (the default), acf-mcp has no authentication — the local client is the trust boundary. In HTTP mode, you bring your own authentication gateway. The Ed25519 signature in the footer is the trust mechanism for the OUTPUT, not for the call.

iNote

The doctrine signature proves that what the server producedhas not been tampered with. It does not prove that the call is legitimate. For that, use stdio (local) or an authenticated HTTP gateway.

stdio mode (local)

The default transport. The MCP client launches the acf-mcp binary as a child process and talks to it via stdin/stdout. There is no authentication because there is no network: only a process that already has access to the user’s shell can reach the server. The trust model is the operating system’s.

This is the recommended mode for single-user deployments (one developer, one AI client, one machine).

HTTP mode (multi-user)

The HTTP transport is opt-in (see configuration). It exposes an MCP-over-HTTP endpoint, intended to sit behind your own authentication gateway. The server itself currently ships no key store — you bring your own.

Authorization: Bearer header

The expected usage, in line with MCP-over-HTTP practices, is to pass an API key in the Authorization header.

http

POST /mcp HTTP/1.1
Host: acf.internal.example.com:3000
Authorization: Bearer acfk_4f9b2c8e1d6a3b7f0c5d8e2a9b4c7f1d
Content-Type: application/json

{ "jsonrpc": "2.0", "method": "tools/call", "params": { ... } }

Bring your own gateway

The officially supported approach today: place an authenticated reverse proxy (Caddy, nginx, Cloudflare Access, Tailscale, etc.) in front of acf-mcp HTTP and terminate authentication there. The server has no notion of user; it just does its deterministic job and signs the output.

Caddyfilecaddyfile

# Example: a thin Caddy reverse proxy in front of acf-mcp HTTP
acf.internal.example.com {
  @authed header Authorization "Bearer {env.ACF_INTERNAL_KEY}"
  handle @authed {
    reverse_proxy 127.0.0.1:3000
  }
  respond 401
}

Built-in key generation (planned)

A npx acf-mcp keygen command is planned to mint API keys in the acfk_… format, persisted locally, verifiable without an external dependency. Until then, your gateway (above) remains the authentication entry point.

Rate limits

In HTTP mode the server applies a default rate limit of 60 calls per minute per IP. It is a minimal guard against runaway agent loops; it is not an anti-DDoS strategy. Place a WAF or Cloudflare in front for traffic exposed to the public internet.

The signature remains the root of trust

Whatever the transport, every output embeds doctrine_hash, doctrine_signature and doctrine_public_key. A downstream consumer can therefore validate doctrine authenticity and integrity even without trusting the transport. See doctrine signatures.