Deployment Guide -- Axon MCP

June 30, 2026 · View on GitHub

Deployment patterns for the Axon MCP server. Choose the method that fits your environment.

Local development

Full stack (recommended)

just dev

Current repository just dev starts TEI + Chrome, builds the debug binary, and launches axon mcp as the local worker daemon. Use axon serve explicitly when you need the unified HTTP API, MCP HTTP endpoint, web panel, and in-process workers on port 8001.

MCP server only

# Start infrastructure
just services-up

# Run MCP server standalone (stdio)
axon mcp

# Or HTTP transport
axon serve mcp

Minimal local runtime

axon mcp

Jobs use SQLite and in-process workers. Qdrant and TEI are still required for embedding/search paths.

Docker

Infrastructure + app containers

# Start local infrastructure (TEI + Chrome; Qdrant is remote by default)
just services-up

Use just qdrant-up only for an intentional local Qdrant fallback.

Docker Compose split

File	Contents	Env file
`docker-compose.prod.yaml`	Axon server, Qdrant, TEI, Chrome	`~/.axon/.env`

The compose file creates the axon bridge network. Pass --env-file ~/.axon/.env when running it directly so the canonical appdata env file is used for ${VAR} interpolation.

GPU acceleration

For NVIDIA hosts with GPU-accelerated TEI:

docker compose --env-file ~/.axon/.env -f docker-compose.prod.yaml up -d axon-qdrant axon-tei axon-chrome

CPU-only hosts should override the TEI image/settings or point TEI_URL at an external CPU embedding endpoint.

Local app runtime

The tracked compose file starts the Axon server plus Qdrant, TEI, and Chrome. Run axon serve locally only when you want to bypass Compose and run the unified HTTP API, MCP HTTP endpoint, web panel, and in-process workers directly.

Build

# Build Chrome image
docker compose --env-file ~/.axon/.env -f docker-compose.prod.yaml build axon-chrome

Run compose commands from the repo root. Host-side state defaults to ${HOME}/.axon through AXON_HOME; the container sees that same appdata tree as /home/axon/.axon.

Health checks

# Infrastructure
docker compose --env-file ~/.axon/.env -f docker-compose.prod.yaml ps

# Service connectivity
./scripts/axon doctor

Data volumes

Runtime data uses ${AXON_DATA_DIR:-~/.axon}/...; Docker bind mounts use ${AXON_HOME:-$HOME/.axon}/.... Keep them aligned unless relocating the entire Axon appdata tree.

Volume	Content
`$AXON_DATA_DIR/jobs.db`	SQLite job database
`$AXON_DATA_DIR/qdrant`	Qdrant vector storage
`$AXON_DATA_DIR/tei`	TEI model cache
`$AXON_DATA_DIR/artifacts`	MCP response artifacts
`$AXON_DATA_DIR/output`	CLI output files