Configuration Guide
Audience: Reseller deployment leads and support engineers configuring VCONIC for a customer environment.
Reseller lens
VCONIC is configured entirely via environment variables. Every variable documented here exists in .env.example on main — no invented flags. Treat that file as the source of truth and this guide as the reseller-lens grouping with one-line meanings.
Database
SUPABASE_URL
yes
—
Supabase project URL
SUPABASE_ANON_KEY
yes
—
Anon key from project API settings
SUPABASE_SERVICE_ROLE_KEY
no
—
Service role (use sparingly; bypasses RLS)
DB_TYPE
no
supabase
Backend: supabase or mongodb
MONGO_URL
no
—
Only when DB_TYPE=mongodb
MONGO_DB_NAME
no
vcon
Only when DB_TYPE=mongodb
MCP transport
MCP_TRANSPORT
stdio
stdio or http
MCP_HTTP_HOST
127.0.0.1
Use 0.0.0.0 in containers
MCP_HTTP_PORT
3000
MCP_HTTP_STATELESS
false
Set true to disable session tracking
MCP_HTTP_JSON_ONLY
false
Set true to disable SSE streaming
MCP_HTTP_DNS_PROTECTION
false
DNS rebinding protection
MCP_HTTP_ALLOWED_HOSTS
—
Comma-separated whitelist
MCP_HTTP_ALLOWED_ORIGINS
—
Comma-separated whitelist
REST API (HTTP transport only)
REST_API_ENABLED
true
Enable REST endpoints alongside MCP
REST_API_BASE_PATH
/api/v1
Endpoint prefix
CORS_ORIGIN
*
Allowed CORS origin for the REST API (the server does not read MCP_HTTP_CORS or MCP_HTTP_CORS_ORIGIN)
Authentication
API key auth covers both REST and MCP HTTP endpoints.
API_AUTH_REQUIRED
true
Require auth on REST + MCP HTTP
API_KEYS
—
Comma-separated keys with full read/write/delete access
API_KEYS_READONLY
—
Comma-separated read-only keys (GET-only on REST, no write tools on MCP)
API_KEY_HEADER
authorization
Header to read key from
Default header authorization accepts Authorization: Bearer <key>. Set API_KEY_HEADER=x-api-key to use a plain custom header.
Misconfiguration trap: API_AUTH_REQUIRED=true with no keys in either variable returns 503 Service Unavailable until a key is set.
Read-only keys. Give external consumers an API_KEYS_READONLY key. Those keys get 403 Forbidden on any non-GET REST request and cannot call write category MCP tools. API_KEYS keys can delete the entire corpus, so never hand one out. A key in both variables is read-only. Details: Configuration → API Keys and Read-Only Access.
Multi-tenant (RLS)
RLS_ENABLED
false
Enable Row-Level Security policies
RLS_DEBUG
false
Log RLS decisions (verbose)
CURRENT_TENANT_ID
—
Tenant ID applied to service-role queries
TENANT_ATTACHMENT_TYPE
tenant
Attachment type extracted as tenant marker
TENANT_JSON_PATH
id
Dot-path inside attachment body for the tenant id
Deep dive: RLS Multi-Tenant.
Tool surface
Restrict the tool catalog exposed to clients.
MCP_TOOLS_PROFILE
full
One of full, readonly, user, admin, minimal, public
MCP_ENABLED_CATEGORIES
—
Comma-separated: e.g. read,write
MCP_DISABLED_CATEGORIES
—
Comma-separated: e.g. analytics
MCP_DISABLED_TOOLS
—
Specific tool names: e.g. delete_vcon
Embeddings
Semantic and hybrid search require an embeddings provider.
OPENAI_API_KEY
for OpenAI direct
Key for embedding generation
LITELLM_PROXY_URL
for LiteLLM
Proxy endpoint, e.g. http://localhost:4000
LITELLM_MASTER_KEY
for LiteLLM
LiteLLM master key
EMBEDDING_PROVIDER
no
Forces the provider used to embed search queries: supabase or openai. Unset, the server uses openai when OPENAI_API_KEY is set, otherwise supabase. Use the provider that built the corpus; vcon_embeddings.embedding_model records it, and mixing providers makes similarity scores meaningless
If neither is set, content search and tag search still work; semantic search returns no results.
Caching
REDIS_URL
—
e.g. redis://localhost:6379
VCON_REDIS_EXPIRY
3600
TTL in seconds
Plugins
The plugin loader accepts module paths. The license variables apply only to plugins that opt in to license-key gating; the core server runs without them.
VCON_PLUGINS_PATH
—
Comma-separated module paths
VCON_LICENSE_KEY
—
Optional, plugin-defined
VCON_OFFLINE_MODE
false
Optional, plugin-defined
Architecture: Plugin reference, Plugin development.
Media storage
AWS_REGION
us-east-1
S3 region for media storage, used when the media storage config sets no region
Build and migration variables
VCON_MCP_VERSION
Version string reported by /version and in logs. Set at image build time; dev when unset
VCON_MCP_GIT_COMMIT
Commit reported with the version. unknown when unset
VCON_MCP_BUILD_TIME
Build timestamp. Falls back to server start time when unset
SUPABASE_DB_URL
Postgres connection string. Not read by the server. The Docker image's migrate and migrate-status commands require it to run supabase db push and supabase migration list
Observability
OTEL_ENABLED
true
Enable OpenTelemetry
OTEL_EXPORTER_TYPE
console
console (no-op) or otlp
OTEL_ENDPOINT
http://localhost:4318
OTLP collector
OTEL_SERVICE_NAME
vcon-mcp-server
Span service name
LOG_LEVEL
info
Pino log level
MCP_DEBUG
false
MCP protocol-level debug logging
Deep dive: Observability.
Worked scenarios
Claude Desktop (stdio)
Minimum env: SUPABASE_URL, SUPABASE_ANON_KEY. Everything else default.
Shared HTTP deployment
Read-only analytics user
See also
Last updated