# 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: `{ "": {"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`) |