environment-variables.md

Environment Variables Reference

Introduction

All configuration is via environment variables, set in a .env file, directly in the shell, or in your MCP client configuration (env block in .mcp.json). The canonical source of truth for all variables is app/settings.py.

MCP clients such as Claude Code support environment variable expansion using ${VAR} or ${VAR:-default} syntax. For details, see: https://docs.claude.com/en/docs/claude-code/mcp#environment-variable-expansion-in-mcp-json

Core Settings

Variable	Type	Default	Description
LOG_LEVEL	string	ERROR	Application log level. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL. The single effective verbosity control: the server aligns FastMCP's non-propagating logger tree and, on HTTP transports, uvicorn's loggers with this level
STORAGE_BACKEND	string	sqlite	Database backend. Options: sqlite, postgresql
DB_PATH	path	~/.mcp/context_storage.db	SQLite database file location. Only used when STORAGE_BACKEND=sqlite. Blank or whitespace-only values are rejected at startup as a configuration error (exit 78)
MAX_IMAGE_SIZE_MB	integer	10	Maximum size per image attachment in megabytes (minimum 1)
MAX_TOTAL_SIZE_MB	integer	100	Maximum total request size in megabytes (minimum 1)
DISABLED_TOOLS	string	(empty)	Comma-separated list of MCP tools to disable (e.g., delete_context,update_context)

Transport Settings

Variable	Type	Default	Constraints	Description
MCP_TRANSPORT	string	stdio		Transport mode. Options: stdio, http, streamable-http, sse
FASTMCP_HOST	string	0.0.0.0		HTTP bind address. Use 0.0.0.0 for Docker
FASTMCP_PORT	integer	8000	1-65535	HTTP port number
FASTMCP_STATELESS_HTTP	boolean	true		Enable stateless HTTP mode for horizontal scaling. Set to false only if you need server-side MCP session tracking
FASTMCP_ENABLE_RICH_LOGGING	boolean	true		Rich/ANSI-formatted FastMCP logging. Consumed by FastMCP at import time, so it is intentionally absent from app/settings.py and server.json (per FASTMCP_* governance). Set false in Docker/cloud/JSON-log-pipeline deployments to emit plain logs; the shipped images, Compose files, and Helm chart already set it false.
FASTMCP_JSON_RESPONSE	boolean	false		Plain-JSON HTTP responses instead of Server-Sent Events for the http/streamable-http transports. Consumed by FastMCP (no explicit run argument overrides it, so this env var is the only switch); intentionally absent from app/settings.py and server.json (per FASTMCP_* governance). Set true when a proxy or MCP client cannot consume text/event-stream responses
FASTMCP_LOG_LEVEL	string	INFO		Import-time level of FastMCP's own non-propagating logger tree. At startup the server re-aligns that tree with LOG_LEVEL, so this affects only lines emitted before the application configures logging; intentionally absent from app/settings.py and server.json (per FASTMCP_* governance)
FASTMCP_LOG_ENABLED	boolean	true		Whether FastMCP installs its own log handler at import time. false removes FastMCP-internal log output entirely; intentionally absent from app/settings.py and server.json (per FASTMCP_* governance)

FastMCP's FASTMCP_STRICT_INPUT_VALIDATION is intentionally INERT for this server: the FastMCP() constructor pins strict_input_validation=False explicitly, because lax scalar coercion is load-bearing -- real MCP clients intermittently send scalar parameters as JSON-encoded strings, and the JSON-string middleware repairs only array and object parameters. Setting the variable has no effect (an explicit constructor argument overrides the environment fallback), the same class as FASTMCP_TRANSPORT (superseded by MCP_TRANSPORT).

Authentication Settings

Variable	Type	Default	Description
MCP_AUTH_PROVIDER	string	none	Authentication provider. Options: none (no auth), simple_token (bearer token)
MCP_AUTH_TOKEN	secret	(none)	Bearer token for HTTP authentication. Required when MCP_AUTH_PROVIDER=simple_token
MCP_AUTH_CLIENT_ID	string	mcp-client	Client ID assigned to authenticated requests. Used with simple_token provider

For detailed authentication setup, see the Authentication Guide.

Server Instructions

Variable	Type	Default	Description
MCP_SERVER_INSTRUCTIONS	string	(built-in default)	Custom server instructions text sent to MCP clients during initialization. Overrides the built-in default. Set to empty string to disable instructions entirely

Ollama Settings (Shared)

Variable	Type	Default	Constraints	Description
OLLAMA_HOST	string	http://localhost:11434		Ollama server URL. Shared by all features using Ollama (embeddings, summary generation)
OLLAMA_AUTO_PULL	boolean	true		Automatically pull missing Ollama models on startup. Set to false for air-gapped environments or CI/CD pipelines
OLLAMA_PULL_TIMEOUT_S	integer	900	30-3600	Timeout in seconds for pulling Ollama models. Increase for slow networks or large models

Embedding Settings

General

Variable	Type	Default	Constraints	Description
ENABLE_EMBEDDING_GENERATION	boolean	true		Enable embedding generation for stored context entries. If true and dependencies are not met, server will NOT start. Set to false to disable embeddings entirely
EMBEDDING_PROVIDER	string	ollama		Embedding provider. Options: ollama, openai, azure, huggingface, voyage
EMBEDDING_MODEL	string	qwen3-embedding:0.6b		Embedding model name (provider-specific)
EMBEDDING_DIM	integer	1024	1-4096, must be >0	Embedding vector dimensions. Changing after initial setup requires database migration. On PostgreSQL with ENABLE_EMBEDDING_COMPRESSION=false the maximum is 2000: pgvector caps its HNSW index at 2000 dimensions for the vector type, and values above that are rejected at startup as a configuration error (exit 78); set ENABLE_EMBEDDING_COMPRESSION=true to lift this limit (compressed payloads are stored as BYTEA with no pgvector dimension cap)
EMBEDDING_TIMEOUT_S	float	240.0	>0, <=300	Timeout in seconds for embedding generation API calls
EMBEDDING_RETRY_MAX_ATTEMPTS	integer	5	1-10	Maximum number of retry attempts for embedding generation
EMBEDDING_RETRY_BASE_DELAY_S	float	1.0	>0, <=30	Base delay in seconds between retry attempts (with exponential backoff)
EMBEDDING_MAX_CONCURRENT	integer	3	1-20	Maximum concurrent embedding generation operations. Limits parallel provider requests to prevent overload

For detailed embedding setup and provider selection, see the Semantic Search Guide. To change EMBEDDING_MODEL on an existing database, run the migration CLI's --re-embed flag; changing EMBEDDING_DIM requires a database rebuild. Both procedures are documented in Changing the Embedding Model or Dimensions.

Ollama-Specific Embedding Settings

Variable	Type	Default	Constraints	Description
EMBEDDING_OLLAMA_NUM_CTX	integer	4096	512-2097152	Ollama embedding context length in tokens. Must match or exceed model capabilities
EMBEDDING_OLLAMA_TRUNCATE	boolean	false		Control text truncation when exceeding embedding context length. false: returns error on exceeded context. true: silently truncates input (may degrade embedding quality)

OpenAI-Specific Embedding Settings

Variable	Type	Default	Description
OPENAI_API_KEY	secret	(none)	OpenAI API key
OPENAI_API_BASE	string	(none)	Custom base URL for OpenAI-compatible APIs
OPENAI_ORGANIZATION	string	(none)	OpenAI organization ID

Azure OpenAI-Specific Embedding Settings

Variable	Type	Default	Description
AZURE_OPENAI_API_KEY	secret	(none)	Azure OpenAI API key
AZURE_OPENAI_ENDPOINT	string	(none)	Azure OpenAI endpoint URL
AZURE_OPENAI_API_VERSION	string	2024-02-01	Azure OpenAI API version
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME	string	(none)	Azure OpenAI embedding deployment name

HuggingFace-Specific Embedding Settings

Variable	Type	Default	Description
HUGGINGFACEHUB_API_TOKEN	secret	(none)	HuggingFace Hub API token

Voyage AI-Specific Embedding Settings

Variable	Type	Default	Constraints	Description
VOYAGE_API_KEY	secret	(none)		Voyage AI API key
VOYAGE_TRUNCATION	boolean	false		Control text truncation when exceeding context length. false: returns error. true: silently truncates input
VOYAGE_BATCH_SIZE	integer	7	1-128	Number of texts per API call

Summary Generation Settings

Variable	Type	Default	Constraints	Description
ENABLE_SUMMARY_GENERATION	boolean	true		Enable summary generation for stored context entries. If true and dependencies are not met, server will NOT start. Set to false to disable summaries entirely
SUMMARY_PROVIDER	string	ollama		Summary provider. Options: ollama, openai, anthropic
SUMMARY_MODEL	string	qwen3:0.6b		Summary generation model name. Alternatives: qwen3:1.7b, qwen3:4b, qwen3:8b
SUMMARY_MAX_TOKENS	integer	4000	50-16384	Maximum output tokens for summary generation. Acts as a safety ceiling passed to the LLM API. Increase if summaries are truncated by reasoning models
SUMMARY_TIMEOUT_S	float	240.0	>0, <=600	Timeout in seconds for summary generation API calls
SUMMARY_RETRY_MAX_ATTEMPTS	integer	5	1-10	Maximum number of retry attempts for summary generation
SUMMARY_RETRY_BASE_DELAY_S	float	3.0	>0, <=30	Base delay in seconds between retry attempts (with exponential backoff)
SUMMARY_MAX_CONCURRENT	integer	2	1-20	Maximum concurrent calls against the summary model. Governs the unified summary-model budget shared by BOTH the flat document summary AND every index_tree per-node summary, so peak load on the single model is capped at this value regardless of overlap
SUMMARY_PROMPT	string	(built-in default)		Custom summarization prompt. Overrides both source-specific defaults (user/agent get same prompt). For Qwen3, include /no_think to disable reasoning mode
SUMMARY_MIN_CONTENT_LENGTH	integer	500	0-10000	Minimum text content length (characters) to trigger summary generation. Content shorter than this is not summarized. Set to 0 to always generate summaries
SUMMARY_OLLAMA_NUM_CTX	integer	32768	512-2097152	Ollama summary context length in tokens. Must match or exceed model capabilities
SUMMARY_OLLAMA_TRUNCATE	boolean	false		Control text truncation when exceeding summary context length. false: returns error. true: silently truncates input (summary from incomplete text)
SUMMARY_OPENAI_REASONING_EFFORT	string	low		Reasoning effort for OpenAI reasoning models. Valid: gpt-5: low/medium/high; gpt-5.1+: none/low/medium/high/xhigh. Default low is universally valid. Set to empty to omit
SUMMARY_ANTHROPIC_EFFORT	string	(none)		Effort level for Anthropic Claude models. Valid: max, high, medium, low. Controls adaptive thinking. Default: not sent (required for models like Haiku 4.5 that do not support it)
OPENAI_API_KEY	secret	(none)		OpenAI API key (shared with embedding provider when both use OpenAI)
OPENAI_API_BASE	string	(none)		Custom base URL for OpenAI-compatible APIs (shared with embedding provider when both use OpenAI)
ANTHROPIC_API_KEY	secret	(none)		Anthropic API key for summary generation

For detailed summary setup and provider selection, see the Summary Generation Guide.

Retrieval Settings

Variable	Type	Default	Description
GET_CONTEXT_BY_IDS_INCLUDE_SUMMARY	boolean	false	Whether get_context_by_ids includes the summary field in each returned entry. Tri-state contract: when false (default), the summary key is omitted entirely so consumers reading entry.get('summary') receive None -- the conventional Python signal for "feature disabled"; when true with a stored non-empty summary, the value is returned verbatim; when true but the stored summary is NULL or empty, the value is normalized to '' (empty string) signaling "feature on, no data yet". The text_content field always contains the full untruncated text regardless of this toggle. Does not affect search tools, which always emit summary as a string.

Semantic Search Settings

Variable	Type	Default	Description
ENABLE_SEMANTIC_SEARCH	tri-state	auto	Controls registration of the semantic_search_context tool. auto (default): register when an embedding provider is available (embedding generation is on by default), otherwise skip quietly. true: registers only when a provider is available, otherwise a warning is logged and the tool is NOT registered (true cannot force it on without a provider). false: force off. The boolean spellings true/false/1/0/yes/no/on/off are also accepted

For detailed semantic search setup, see the Semantic Search Guide.

Full-Text Search Settings

Variable	Type	Default	Description
ENABLE_FTS	tri-state	auto	Controls registration of the fts_search_context tool. auto (default): register; full-text search uses built-in database capabilities and needs no extra dependencies. true: force on. false: force off. The boolean spellings true/false/1/0/yes/no/on/off are also accepted
FTS_LANGUAGE	string	english	Language for FTS stemming. PostgreSQL supports 29 languages. Valid options: simple, arabic, armenian, basque, catalan, danish, dutch, english, finnish, french, german, greek, hindi, hungarian, indonesian, irish, italian, lithuanian, nepali, norwegian, portuguese, romanian, russian, serbian, spanish, swedish, tamil, turkish, yiddish

For detailed full-text search setup, see the Full-Text Search Guide.

FTS Passage Extraction Settings

Variable	Type	Default	Constraints	Description
FTS_RERANK_WINDOW_SIZE	integer	750	100-2000	Characters of context around each FTS match for reranking passage extraction
FTS_RERANK_GAP_MERGE	integer	100	0-500	Merge FTS match regions within this character distance

Hybrid Search Settings

Variable	Type	Default	Constraints	Description
ENABLE_HYBRID_SEARCH	tri-state	auto		Controls registration of the hybrid_search_context tool. auto (default) and true both register when at least one of full-text or semantic search is available, otherwise skip with a warning (hybrid has no underlying mode to fuse, so true cannot force the tool on with neither). false: force off. The boolean spellings true/false/1/0/yes/no/on/off are also accepted
HYBRID_RRF_K	integer	60	1-1000	RRF smoothing constant. Higher values give more uniform treatment across ranks
HYBRID_RRF_OVERFETCH	integer	2	1-10	Multiplier for over-fetching results before RRF fusion
HYBRID_FTS_OR_THRESHOLD	integer	4	2-20	Minimum number of significant query terms to switch FTS from AND to OR logic

For detailed hybrid search setup, see the Hybrid Search Guide.

Grep, Navigation & Partial-Read Settings

Variable	Type	Default	Constraints	Description
ENABLE_GREP_CONTEXT	tri-state	auto		Register the grep_context tool. auto (default) and true register it (matching is pure-Python, no extra dependencies); false forces it off
ENABLE_CONTEXT_NAVIGATION	tri-state	auto		Register the navigate_context tool (code-derived Markdown index_tree). auto/true register; false forces off
ENABLE_CONTEXT_RANGE	tri-state	auto		Register the read_context_range tool (partial read by char/line/node). auto/true register; false forces off
GREP_MAX_MATCHES_CAP	integer	1000	>= 1	Hard ceiling applied to grep_context max_matches per request
GREP_MAX_CONTEXT_LINES	integer	20	>= 0	Hard ceiling applied to grep_context context_lines per request
GREP_MAX_ENTRIES_SCANNED	integer	1000	>= 1	Hard ceiling on the number of entries a grep scan visits
GREP_AGGREGATE_BYTES_BUDGET	integer	67108864	>= 1	Approximate resident-memory cap (summed code-point length of fetched text) before a scan stops; the first entry that crosses the budget is still scanned
GREP_REGEX_TIMEOUT_S	float	5.0	> 0	Per-entry timeout for is_regex=true matching (ReDoS guard); a timeout skips that entry, never aborts the read
GREP_REGEX_TOTAL_TIMEOUT_S	float	30.0	> 0	Aggregate wall-clock budget for a whole is_regex=true scan; when exceeded it stops with truncated=true (per-entry timeout bounds one entry)
GREP_MAX_PATTERN_CHARS	integer	32768	>= 1	Maximum grep_context pattern length in characters (compilation runs before any matching timeout, so an unbounded pattern could stall a request just to compile; 32 KiB fits any realistic pattern while keeping a worst-case compile in the low milliseconds)

For when to use grep vs full-text vs semantic search, and the navigate -> read workflow, see Grep, Navigation & Partial Reads.

Index Tree Node Summary Settings

Variable	Type	Default	Constraints	Description
ENABLE_INDEX_TREE_NODE_SUMMARIES	boolean	true		Generate per-node LLM summaries for the navigate_context index_tree and provision the context_index_nodes table. Additive/never-raise (never aborts a store)
INDEX_TREE_NODE_SUMMARY_PROMPT	string	(built-in)		Override the per-node summary system prompt. Empty resolves to a dedicated short one-sentence-abstract prompt
INDEX_TREE_NODE_SUMMARY_MIN_CONTENT_LENGTH	integer	500	0-100000	Heading sections shorter than this (characters) skip node-summary generation (0 = always)
INDEX_TREE_NODE_SUMMARY_TIMEOUT_S	float	240.0	> 0, <= 600	Per-node summary timeout in seconds; a timeout omits that node, never aborts the store
INDEX_TREE_NODE_SUMMARY_MAX_CONCURRENT	integer	min(cpu_count,4)	1-32	Node-task launch/fan-out cap: how many per-node summary coroutines are launched concurrently. NOT a second summary-model budget — calls against the model are bounded by the shared SUMMARY_MAX_CONCURRENT budget

Per-node summaries reuse the configured summary provider (no second client) via a dedicated short prompt, and they share the single SUMMARY_MAX_CONCURRENT model-concurrency budget with the flat document summary (so INDEX_TREE_NODE_SUMMARY_MAX_CONCURRENT only bounds how many node coroutines are launched, not how many hit the model at once). They run in-request, overlapped with embedding/compression and started right after the flat summary, and a node-summary failure or timeout never aborts the store. Set ENABLE_INDEX_TREE_NODE_SUMMARIES=false to keep navigation purely code-derived with no per-store LLM cost and no node table.

Search Settings

Variable	Type	Default	Constraints	Description
SEARCH_DEFAULT_SORT_BY	string	relevance		Default sort order for search results. Currently only relevance is supported
SEARCH_TRUNCATION_LENGTH	integer	300	50-1000	Maximum character length for truncated text_content in search results

Chunking Settings

Variable	Type	Default	Constraints	Description
ENABLE_CHUNKING	boolean	true		Enable text chunking for embedding generation
CHUNK_SIZE	integer	1500	100-10000	Target chunk size in characters
CHUNK_OVERLAP	integer	150	0-500, must be < CHUNK_SIZE	Overlap between chunks in characters
CHUNK_AGGREGATION	string	max		Chunk score aggregation method. Currently only max is supported
CHUNK_DEDUP_OVERFETCH	integer	5	1-20	Multiplier for fetching extra chunks before deduplication

Reranking Settings

Variable	Type	Default	Constraints	Description
ENABLE_RERANKING	boolean	true		Enable cross-encoder reranking of search results
RERANKING_PROVIDER	string	flashrank		Reranking provider
RERANKING_MODEL	string	ms-marco-MiniLM-L-12-v2		Reranking model name (~34MB)
RERANKING_MAX_LENGTH	integer	512	128-2048	Maximum input length for reranking in tokens
RERANKING_OVERFETCH	integer	4	1-20	Multiplier for over-fetching results before reranking
RERANKING_CACHE_DIR	string	(system cache)		Directory for caching reranking models
RERANKING_CHARS_PER_TOKEN	float	4.0	2.0-8.0	Estimated characters per token for passage size validation. Default 4.0 for English. Use 3.0-3.5 for multilingual/code
RERANKING_INTRA_OP_THREADS	integer	0	>=0	ONNX Runtime intra-operation parallelism threads. 0 = auto-detect. In containers, set to match CPU quota
RERANKING_CPU_MEM_ARENA	boolean	false		Enable ONNX Runtime CPU memory arena. false: reduces RAM usage. true: slightly faster inference, higher memory
RERANKING_BATCH_SIZE	integer	32	>0	Maximum passages per ONNX Runtime inference batch

Embedding Compression Settings

Embedding compression is on by default in v3.0.0. The storage write path replaces fp32 embeddings with bit-packed compressed payloads and the search read path scores directly over the compressed payloads. Set ENABLE_EMBEDDING_COMPRESSION=false to opt out and use fp32 storage. See the Embedding Compression Guide for architecture, storage math, the migration CLI, and the multi-pod seed-locked invariant.

Variable	Type	Default	Constraints	Description
ENABLE_EMBEDDING_COMPRESSION	boolean	true		Enable TurboQuant embedding compression at storage time. Default true in v3.0.0. Set to false to opt out and keep fp32 storage. When true, fp32 embeddings are replaced with bit-packed compressed payloads (~8x storage reduction at default bits=4)
COMPRESSION_PROVIDER	string	turboquant		Compression provider. v3.0.0 supports only turboquant
COMPRESSION_BITS	integer	4	2-4	Bits per coordinate. 2 = 16x compression, 3 = ~11x, 4 = 8x. Default 4 = ~8x with high recall. The lower bound of 2 is required by variant='ip' (the inner-product variant reserves one bit per coordinate for the QJL sign)
COMPRESSION_VARIANT	string	ip		Compression variant. ip (default): Algorithm 2 with QJL, unbiased inner-product estimator. mse: Algorithm 1, L2-optimal reconstruction
COMPRESSION_SEED	integer	0	0..4294967295	Rotation matrix seed, packed into the compressed payload as an unsigned 32-bit field, so it must fit [0, 4294967295]. Default 0. Load-bearing invariant: rotations are deterministic given the seed; changing the seed AFTER any compressed data has been stored will corrupt all decode/search operations. Persisted in compression_metadata at first startup and validated on each subsequent start (exit 78 on mismatch)
COMPRESSION_MAX_CONCURRENT	integer	min(cpu_count, 4)	1-32	Max concurrent compression encode workers dispatched to threads; the CPU-bound codec section is serialized by a process-wide BLAS-limits lock, so this bounds worker fan-out, not CPU parallelism. Separate from the I/O-bound EMBEDDING_MAX_CONCURRENT and SUMMARY_MAX_CONCURRENT semaphores

LangSmith Tracing Settings

Variable	Type	Default	Description
LANGSMITH_TRACING	boolean	false	Enable LangSmith tracing for cost tracking and observability
LANGSMITH_API_KEY	secret	(none)	LangSmith API key for tracing
LANGSMITH_ENDPOINT	string	https://api.smith.langchain.com	LangSmith API endpoint
LANGSMITH_PROJECT	string	mcp-context-server	LangSmith project name for grouping traces

Metadata Indexing Settings

Variable	Type	Default	Description
METADATA_INDEXED_FIELDS	string	status,agent_name,task_name,project,report_type,references:object,technologies:array	Comma-separated list of metadata fields to index with optional type hints (field:type format). Supported types: string (default), integer, boolean, float, array, object. Array/object types use PostgreSQL GIN indexes (skipped in SQLite). Field names must match ^[A-Za-z_][A-Za-z0-9_]*$ (a letter or underscore followed by letters, digits, or underscores), must be at most 50 characters (so the generated idx_metadata_ index name fits PostgreSQL's 63-byte identifier limit), and must be unique under case folding (two names differing only in case collide on SQLite); names violating any of these are rejected at startup as a configuration error (exit 78). On PostgreSQL, generated index identifiers are double-quoted so identifier case is preserved exactly as configured
METADATA_INDEX_SYNC_MODE	string	additive	How to handle index mismatches at startup. Options: strict (fail if mismatch), auto (sync: add missing, drop extra), warn (log warnings), additive (add missing, never drop). Strict mode verifies indexes without provisioning them, so it requires the indexes to be pre-provisioned: bootstrap a fresh database once in additive or auto mode before flipping to strict

For detailed metadata usage, see the Metadata Guide.

SQLite Connection Pool Settings

These settings apply only when STORAGE_BACKEND=sqlite.

Variable	Type	Default	Description
POOL_MAX_READERS	integer	8	Maximum number of reader connections in the SQLite connection pool (minimum 1)
POOL_MAX_WRITERS	integer	1	Maximum number of writer connections in the SQLite connection pool (minimum 1)
POOL_CONNECTION_TIMEOUT_S	float	10.0	Connection acquisition timeout in seconds (must be > 0)
POOL_IDLE_TIMEOUT_S	float	300.0	Idle connection timeout in seconds (must be > 0)
POOL_HEALTH_CHECK_INTERVAL_S	float	30.0	Interval between connection health checks in seconds (must be > 0)

Database Retry Settings

These settings apply to both backends: the SQLite write queue and the PostgreSQL execute_write path build their retry configuration from the same variables.

Variable	Type	Default	Description
RETRY_MAX_RETRIES	integer	5	Total attempt budget for transient database errors (minimum 1; 1 means one attempt, no retries)
RETRY_BASE_DELAY_S	float	0.5	Base delay in seconds between retries (minimum 0)
RETRY_MAX_DELAY_S	float	10.0	Maximum delay in seconds between retries (minimum 0)
RETRY_JITTER	boolean	true	Add random jitter to retry delays to prevent thundering herd
RETRY_BACKOFF_FACTOR	float	2.0	Exponential backoff multiplier for retry delays (minimum 1)

SQLite PRAGMA Settings

These settings apply only when STORAGE_BACKEND=sqlite.

Variable	Type	Default	Description
SQLITE_FOREIGN_KEYS	boolean	true	Enable foreign key enforcement
SQLITE_JOURNAL_MODE	string	WAL	SQLite journal mode. WAL recommended for concurrent reads
SQLITE_SYNCHRONOUS	string	NORMAL	SQLite synchronous mode. NORMAL balances safety and performance
SQLITE_TEMP_STORE	string	MEMORY	Where to store temporary tables. MEMORY for better performance
SQLITE_MMAP_SIZE	integer	268435456	Memory-mapped I/O size in bytes. Default: 256MB
SQLITE_CACHE_SIZE	integer	-64000	SQLite page cache size. Negative value = kilobytes. Default: -64000 (64MB)
SQLITE_PAGE_SIZE	integer	4096	SQLite page size in bytes
SQLITE_WAL_AUTOCHECKPOINT	integer	1000	Number of WAL frames before auto-checkpoint
SQLITE_BUSY_TIMEOUT_MS	integer	(derived)	SQLite busy timeout in milliseconds (minimum 0). Default: derived from POOL_CONNECTION_TIMEOUT_S * 1000
SQLITE_WAL_CHECKPOINT	string	PASSIVE	WAL checkpoint mode

Circuit Breaker Settings

These settings apply to both backends: the SQLite connection layer and the PostgreSQL execute_read/execute_write/begin_transaction paths build their circuit breaker from the same three variables.

Variable	Type	Default	Description
CIRCUIT_BREAKER_FAILURE_THRESHOLD	integer	10	Number of consecutive failures before circuit opens (minimum 1)
CIRCUIT_BREAKER_RECOVERY_TIMEOUT_S	float	30.0	Seconds to wait before attempting recovery from open circuit (must be > 0)
CIRCUIT_BREAKER_HALF_OPEN_MAX_CALLS	integer	5	Maximum test calls allowed in half-open state (minimum 1)

SQLite Operation Timeout Settings

These settings apply only when STORAGE_BACKEND=sqlite.

Variable	Type	Default	Description
SHUTDOWN_TIMEOUT_S	float	10.0	Graceful shutdown timeout in seconds (must be > 0)
SHUTDOWN_TIMEOUT_TEST_S	float	5.0	Shutdown timeout for test environments in seconds (must be > 0)
QUEUE_TIMEOUT_S	float	1.0	Write queue timeout in seconds (must be > 0)
QUEUE_TIMEOUT_TEST_S	float	0.1	Write queue timeout for test environments in seconds (must be > 0)

PostgreSQL Connection Settings

These settings apply only when STORAGE_BACKEND=postgresql.

Variable	Type	Default	Description
POSTGRESQL_CONNECTION_STRING	secret	(none)	Full PostgreSQL connection string. When provided, overrides individual host/port/user/password/database settings
POSTGRESQL_HOST	string	localhost	PostgreSQL server host
POSTGRESQL_PORT	integer	5432	PostgreSQL server port. Valid range 1-65535; an out-of-range value fails at startup (exit 78)
POSTGRESQL_USER	string	postgres	PostgreSQL username
POSTGRESQL_PASSWORD	secret	postgres	PostgreSQL password
POSTGRESQL_DATABASE	string	mcp_context	PostgreSQL database name
POSTGRESQL_SSL_MODE	string	prefer	PostgreSQL SSL mode. Options: disable, allow, prefer, require, verify-ca, verify-full
POSTGRESQL_SCHEMA	string	public	PostgreSQL schema name for table and index operations

For detailed PostgreSQL setup and Supabase integration, see the Database Backends Guide.

PostgreSQL Connection Pool Settings

These settings apply only when STORAGE_BACKEND=postgresql.

Variable	Type	Default	Constraints	Description
POSTGRESQL_POOL_MIN	integer	2	>=0	Minimum connections in the asyncpg connection pool; must not exceed POSTGRESQL_POOL_MAX (rejected at the configuration boundary)
POSTGRESQL_POOL_MAX	integer	20	>=1	Maximum connections in the asyncpg connection pool; must be at least POSTGRESQL_POOL_MIN (rejected at the configuration boundary)
POSTGRESQL_SESSION_POOLER_MAX_CLIENTS	integer	15	>=1	Per-session client cap of an external session-mode pooler (Supabase Session Pooler / Supavisor); advisory startup WARNING about MaxClientsInSessionMode when POSTGRESQL_POOL_MAX exceeds it. Raise on larger tiers. See docs/database-backends.md.
POSTGRESQL_POOL_TIMEOUT_S	float	120.0	>0	asyncpg connection acquire-wait timeout in seconds: how long pool.acquire() waits for a free connection before failing. A startup advisory (INFO) recommends keeping this at or above a floor of max(60, 2 * POSTGRESQL_COMMAND_TIMEOUT_S) so a slow query cannot starve waiters. Embedding generation runs OUTSIDE the connection pool and does not consume pool time, so this timeout does not need to cover embedding latency. For robustness under embedding-write load, scale POSTGRESQL_POOL_MAX (more connections) and POSTGRESQL_COMMAND_TIMEOUT_S (per-query budget) instead.
POSTGRESQL_CONNECT_TIMEOUT_S	float	60.0	>0	Connection ESTABLISHMENT timeout in seconds (TCP connect plus PostgreSQL startup handshake) for each new connection the pool or the pgvector pre-check opens; distinct from POSTGRESQL_POOL_TIMEOUT_S, which bounds waiting for a free pooled connection. Default 60 matches the asyncpg default.
POSTGRESQL_COMMAND_TIMEOUT_S	float	60.0	>0	Default command timeout in seconds; per-connection statement_timeout is 0.9 * this value. fp32 mode (ENABLE_EMBEDDING_COMPRESSION=false) may need a higher value under write concurrency (SQLSTATE 57014). See docs/database-backends.md.
POSTGRESQL_MIGRATION_TIMEOUT_S	float	300.0	>0, <=3600	Timeout in seconds for migration DDL operations (CREATE INDEX, ALTER TABLE). Default: 300s (5 minutes)

PostgreSQL Connection Pool Hardening

These settings apply only when STORAGE_BACKEND=postgresql.

Variable	Type	Default	Constraints	Description
POSTGRESQL_MAX_INACTIVE_LIFETIME_S	float	300.0	>=0	Close idle connections after this many seconds. 0 to disable
POSTGRESQL_MAX_QUERIES	integer	10000	>=0	Recycle connections after this many queries. 0 to disable

PostgreSQL TCP Keepalive Settings

These settings apply only when STORAGE_BACKEND=postgresql.

Variable	Type	Default	Constraints	Description
POSTGRESQL_TCP_KEEPALIVES_IDLE_S	integer	15	>=0	Seconds of idle time before sending first TCP keepalive probe. 0 to disable
POSTGRESQL_TCP_KEEPALIVES_INTERVAL_S	integer	5	>=0	Seconds between subsequent TCP keepalive probes. 0 to disable
POSTGRESQL_TCP_KEEPALIVES_COUNT	integer	3	>=0	Number of failed TCP keepalive probes before connection is considered dead. 0 to disable

PostgreSQL Prepared Statement Cache Settings

These settings apply only when STORAGE_BACKEND=postgresql.

Variable	Type	Default	Constraints	Description
POSTGRESQL_STATEMENT_CACHE_SIZE	integer	100	0-10000	asyncpg prepared statement cache size. Set to 0 when using external connection poolers (PgBouncer transaction mode, Pgpool-II)
POSTGRESQL_MAX_CACHED_STATEMENT_LIFETIME_S	integer	300	0-86400	Maximum lifetime of cached prepared statements in seconds. No effect when POSTGRESQL_STATEMENT_CACHE_SIZE=0
POSTGRESQL_MAX_CACHEABLE_STATEMENT_SIZE	integer	15360	0-1048576	Maximum size of statement to cache in bytes (default: 15KB). No effect when POSTGRESQL_STATEMENT_CACHE_SIZE=0