Configuration#

All settings are read from environment variables or a .env file in the working directory.

Order of precedence#

When the same variable is defined in more than one place, the server resolves it in this order (highest wins):

  1. Shell environment — variables already exported in the process environment take priority over everything else.

  2. .env file — a .env file in the working directory is loaded on startup; values here override compiled-in defaults but are overridden by the shell environment.

  3. Defaults — built-in defaults apply when a variable is absent from both the shell environment and the .env file.

For the minimal set of variables needed to get up and running, see the Configure step in the quickstart guide. The sections below document every user configurable variables, grouped by area.

Core variables#

These variables are required by the server at runtime and at index-build time.

Variable

Required

Description

SQLALCHEMY_CONNECTION_STRING

yes

Postgres + pgvector connection string

OPENAI_API_KEY

yes *

OpenAI key for embeddings (not required when using local embeddings — see Local embeddings below)

CSV_DATA_PATH

yes

Directory of db_*.txt / mkt_cal_*.txt reference files

COLLECTIONS

no

JSON array of vector collections to index and expose as search tools. Defaults to the OneTick documentation collections. See Active collections.

CUSTOM_COLLECTIONS

no

JSON object declaring config-only (no-code) Markdown collections: { "<name>": {"path": ..., "description": ..., "base_url": ...} }. Each name must also be added to COLLECTIONS. See Option 1 — Config only (markdown directories).

Server variables#

Variable

Required

Description

LLMBASE_MCP_TOOLS

no

Comma-separated tool groups to enable (default: all). See Tools.

LLMBASE_MCP_PORT

no

Server port (default 8080)

LLMBASE_MCP_WORKERS

no

Uvicorn worker process count (default 1). One worker already serves many concurrent requests; see Deployment for when to run more.

FASTMCP_HTTP_ALLOWED_HOSTS

no

JSON list of hostnames allowed in the Host header (default: localhost / 127.0.0.1 only). Set this to your public hostname(s) when running behind a reverse proxy, or requests are rejected with 421 Misdirected Request. Accepts fnmatch patterns. See Deployment.

FASTMCP_HTTP_HOST_ORIGIN_PROTECTION

no

Enable Host/Origin validation (default true). Set false to disable if host filtering is already enforced at the proxy. See Deployment.

Local embeddings#

By default the server uses OpenAI to generate embeddings. To run without an OpenAI key, switch to a local sentence-transformer model:

Variable

Required

Description

EMBEDDING_TYPE

no

Set to sentence_transformer to use local embeddings

EMBEDDING_MODEL

no

HuggingFace model name (e.g. all-MiniLM-L6-v2)

When EMBEDDING_TYPE=sentence_transformer is set, OPENAI_API_KEY is not required and the model is downloaded from HuggingFace on first use.

Local embeddings require the local-embeddings extra. If you installed without it, reinstall with:

pip install "onetick-mcp" "onetick-llmbase[local-embeddings]"

Index-build variables#

These variables are used only when running the index build step (python -m onetick_llmbase.build_index).

To re-index a subset of collections without changing COLLECTIONS, pass --only_collections to build_index:

python -m onetick_llmbase.build_index -c onetick_mcp.config --only_collections python-docs,cloud

Query Based / OneTick auth variables#

These variables are required only when the Query Based tool group is enabled. See OneTick WebAPI authentication for a full explanation of each auth mode.

Variable

Required

Description

OTP_AUTH_MODE

for symbology

openid (default), basic, or none. See OneTick WebAPI authentication.

OTP_WEBAPI

for symbology

Set 1 for WebAPI / REST mode

OTP_HTTP_ADDRESS

for symbology

WebAPI gateway URL

OTP_CLIENT_ID

openid mode

OAuth2 client ID

OTP_CLIENT_SECRET

openid mode

OAuth2 client secret

OTP_ACCESS_TOKEN_URL

openid mode

OAuth2 token endpoint

OTP_HTTP_USERNAME

basic mode

HTTP Basic auth username

OTP_HTTP_PASSWORD

basic mode

HTTP Basic auth password

OTP_SYMBOL_UNIVERSE_QUERY_PATH

no

Path to a custom query file. See Programmable Queries.

OTP_QUERY_TIMEOUT

no

Symbology query timeout in seconds (default 120)

MAX_QUERY_SPAN_DAYS

no

Maximum [start, end] span in days the symbology tool will query (default 1). Raise it for non-snapshot custom queries that need multi-day ranges. See Programmable Queries.

Logging variables#

Variable

Required

Description

LOG_DIR

no

Directory for dated log files (default ./logs)

LOG_FILE_PREFIX

no

Log filename prefix (default onetick-mcp)

LOG_LEVEL

no

Log level (default INFO)

LOG_TO_FILE

no

Write dated log files (default true)

LOG_TO_STDOUT

no

Also log to stdout (default true)

LOG_UTC

no

Use UTC for timestamps and daily file rollover (default true)

SSO variables#

SSO is disabled by default. Set SSO_ENABLED=true and supply the variables below to require OIDC JWT validation on all incoming MCP client connections. See MCP server authentication.

Variable

Required

Description

SSO_ENABLED

no

Enable SSO / OIDC token validation (default false)

SSO_ISSUER_URL

for SSO

OIDC provider issuer URL

SSO_AUDIENCE

recommended

Expected token audience. Optional — if unset, the aud claim is not validated (a startup warning is logged); set it (with a matching audience mapper on the provider) to restrict tokens to this server.

SSO_REQUIRED_SCOPES

no

Required token scopes (connect-time gate)

SSO_BASE_URL

for SSO

SSO base URL

SSO_CLIENT_ID

for SSO

SSO client ID

SSO_CLIENT_SECRET

for SSO

SSO client secret

SSO_AUTHORIZATION_ENDPOINT

no

Override the discovered OAuth authorization endpoint (for a non-discoverable provider)

SSO_TOKEN_ENDPOINT

no

Override the discovered OAuth token endpoint

SSO_JWKS_URI

no

Override the discovered JWKS URI

SSO_USERINFO_ENDPOINT

no

Override the discovered OIDC userinfo endpoint

SSO_JWT_SIGNING_KEY

for SSO

Stable secret used to sign MCP-issued tokens. Required when SSO is enabled — the server fails to start if unset. Generate with python -c "import secrets; print(secrets.token_urlsafe(32))".

SSO_STORAGE_ENCRYPTION_KEY

for SSO

Fernet key encrypting the local OAuth state store. Required when SSO is enabled — the server fails to start if unset or invalid. Generate with python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())".

SSO_STORAGE_PATH

no

Directory for the local OAuth state store (default ./auth-data)