Configuration¶
All runtime configuration is via environment variables (read by
pydantic-settings in novelai_image_mcp.settings). The
canonical reference is .env.example
in the repository root.
Loading order¶
Process environment (highest priority)
.envfile in the current working directoryBuilt-in defaults (lowest priority)
The .env file is parsed as UTF-8; unknown keys are ignored; variable
names are case-insensitive (NOVELAI_TOKEN and novelai_token are
equivalent).
NovelAI credentials¶
Variable |
Default |
Required |
Notes |
|---|---|---|---|
|
— |
one of |
Persistent API token (preferred). Get it from https://novelai.net → Account. |
|
— |
one of |
Username (email) for access-key login. |
|
— |
one of |
Account password. Combined with |
Important
Set either NOVELAI_TOKEN or the NOVELAI_USERNAME + NOVELAI_PASSWORD
pair. The server raises RuntimeError at startup if neither is present
(see NovelAISettings.has_credentials).
Endpoints¶
Variable |
Default |
Notes |
|---|---|---|
|
|
Image generation / Director / encode-vibe / suggest-tags endpoints. NovelAI consolidated most third-party API access to |
|
|
Account / subscription / user-data endpoints. Shares the same host as |
|
|
Primary API host for |
|
|
HTTP timeout for any single NovelAI request. |
Tip
Override NOVELAI_IMAGE_BASE_URL to point at a local mock (e.g.
http://localhost:9000) during integration testing. The tests in
apps/server/tests/ use respx
instead and don’t need this.
Generation defaults¶
These tune the defaults used by generate_image (and any other tool that
accepts the same parameters). They are overridable per tool call.
Variable |
Default |
Range |
Notes |
|---|---|---|---|
|
|
See |
V3 / V4 / V4.5 / V5 model id. |
|
|
64–49152, multiple of 64 |
Image width in pixels. |
|
|
64–49152, multiple of 64 |
Image height in pixels. |
|
|
1–50 |
Sampler iterations. |
|
|
0–20 |
Classifier-free guidance scale. |
|
|
See |
Sampler id. |
Client¶
Variable |
Default |
Range |
Notes |
|---|---|---|---|
|
|
1–1024 |
Vibe-transfer encoding cache size. Encoding the same reference twice hits the cache instead of re-calling the API. |
Output¶
Variable |
Default |
Notes |
|---|---|---|
|
|
Directory where generated PNGs are saved. Relative paths resolve against the server’s working directory. The directory is created on demand. |
|
|
Model the standalone 4× upscaler runs on. Only the V5 line supports standalone upscaling ( |
MCP transport¶
Variable |
Default |
Range |
Notes |
|---|---|---|---|
|
|
|
How the server exposes itself to clients. |
|
|
any bind address |
Bind host for the HTTP transport. |
|
|
1–65535 |
Bind port for the HTTP transport. |
|
|
path string |
HTTP path for the MCP endpoint. Full URL: |
|
(empty) |
any token string |
When set, the HTTP transport requires |
|
(framework default) |
|
Log level passed to FastMCP at startup. |
Note
http is the canonical transport name; streamable-http is accepted as a
legacy alias and selects the same transport. MCP_PATH is passed straight to
FastMCP, so changing it moves the endpoint.
Warning
The default MCP_HOST=127.0.0.1 binds to localhost only. To expose the
server to other machines on your LAN, set MCP_HOST=0.0.0.0 — and either set
MCP_AUTH_TOKEN or put it behind TLS termination / an authenticated reverse
proxy. With both MCP_AUTH_TOKEN and MCP_ROUTE_TOKENS unset the HTTP
transport installs no auth middleware at all — the endpoint accepts
unauthenticated clients.
Insiders, routing and audit¶
The X-MCP-Insiders opt-in surface is inert unless a request sends the header.
These variables configure the header names it reads and the side effects it
switches on; the full contract is in
Insiders header, routing and audit.
Variable |
Default |
Notes |
|---|---|---|
|
|
Name of the per-request opt-in header. Lookup is case-insensitive. |
|
|
JSON list. Ordered candidates for the declared model; the first non-empty header wins. |
|
|
JSON list. Ordered candidates for the agent, and the first route source. |
|
|
JSON list. Ordered candidates for the client; the first name containing |
|
|
JSON list. Operator kill switch: a feature listed here stays off no matter what a client sends. |
|
|
While routing is active, write images under |
|
(unset) |
Audit JSONL destination; unset means |
|
(unset) |
JSON object |
Warning
The five list/dict variables above are JSON:
MCP_AGENT_HEADERS='["X-MCP-Agent-ID"]' works, a comma-separated value
raises a settings error, and an empty value is not valid JSON — comment the
line out instead of leaving it blank.
Putting it all together¶
A production-grade .env for a remote streamable-http deployment:
# ── Auth ──
NOVELAI_TOKEN=pst-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# ── Generation defaults (Opus tier, high quality) ──
NOVELAI_DEFAULT_MODEL=nai-diffusion-4-5-full
NOVELAI_DEFAULT_WIDTH=1024
NOVELAI_DEFAULT_HEIGHT=1024
NOVELAI_DEFAULT_STEPS=28
NOVELAI_DEFAULT_SCALE=5.0
NOVELAI_DEFAULT_SAMPLER=k_euler_ancestral
# ── Output (persist to a Docker volume) ──
NOVELAI_OUTPUT_DIR=/app/outputs
# ── Transport ──
MCP_TRANSPORT=http
MCP_HOST=0.0.0.0
MCP_PORT=8000
MCP_PATH=/mcp
# Require "Authorization: Bearer <token>" on the HTTP endpoint. Without it
# the endpoint is open — front it with TLS + a reverse proxy instead.
MCP_AUTH_TOKEN=change-me
# ── Client ──
NOVELAI_VIBE_CACHE_ENTRIES=128
NOVELAI_TIMEOUT=180
Environment in Docker¶
The Dockerfile
reads from .env via docker-compose.yml’s env_file: directive. To
override a single variable at run time without editing .env:
docker compose run -e MCP_PORT=9000 mcp
For Kubernetes, mount the env file as a Secret or use a ConfigMap /
Secret-aware env provider.
See also¶
Transports — stdio vs HTTP trade-offs