Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Variable
Required
Default
Meaning

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

Variable
Default
Meaning

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)

Variable
Default
Meaning

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.

Variable
Default
Meaning

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)

Variable
Default
Meaning

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.

Variable
Default
Meaning

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.

Variable
Required
Meaning

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

Variable
Default
Meaning

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.

Variable
Default
Meaning

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

Variable
Default
Meaning

AWS_REGION

us-east-1

S3 region for media storage, used when the media storage config sets no region

Build and migration variables

Variable
Meaning

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

Variable
Default
Meaning

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