MCP server environment variables

Configure the Vertica MCP server with environment variables and a YAML configuration file.

The Vertica MCP server is configured through a YAML configuration file and environment variables, with the following order of precedence:

Environment variables
YAML configuration file (default path: /opt/vertica/config/mcp_server.yaml)
Built-in defaults

The following sections list the available environment variables and their corresponding YAML keys, grouped by area: server, TLS/SSL, database, storage and secrets, VCluster server, and job queue settings.

Note

Duration values (timeouts, TTLs, and retentions) accept Go duration strings, such as 30s, 5m, 1h30m, or 240h.

Server settings

These variables control the HTTP server's network and request-handling behavior.

Environment variable	YAML key	Default value	Description
`MCP_SERVER_ADDR`	`server_addr`	`:8667`	Listen address for the MCP server (for example, `:8667`).
`MCP_READ_TIMEOUT`	`read_timeout`	`15s`	Maximum duration to read a full HTTP request.
`MCP_WRITE_TIMEOUT`	`write_timeout`	`100s`	Maximum duration to write an HTTP response.
`MCP_IDLE_TIMEOUT`	`idle_timeout`	`60s`	Maximum idle time on keep-alive connections.
`MCP_SHUTDOWN_TIMEOUT`	`shutdown_timeout`	`30s`	Maximum wait time for graceful server shutdown.
`MCP_MAX_HEADER_BYTES`	`max_header_bytes`	`1048576` (1 MB)	Maximum bytes parsed from request headers.
`MCP_LOG_DIR`	`log_dir`	`/opt/vertica/log`	Directory where server log files are written.
`MCP_EXTERNAL_URL`	`external_url`	(empty)	External base URL for building download links (for example, profile exports and query trees). Set this when the server runs behind Docker, proxies, or firewalls so that generated links are reachable from outside.

TLS/SSL settings

The MCP server requires TLS. If it does not find a certificate/key pair at startup, it automatically generates a self-signed CA and server certificate.

Note

MCP_SSL_BASE_PATH is applied first. Individual certificate paths (MCP_SSL_CERT_PATH, and so on) override the paths derived from the base path.

Environment variable	YAML key	Default value	Description
`MCP_SSL_BASE_PATH`	`ssl_base_path`	`/opt/vertica/config/mcp_server`	Base directory for TLS files. Certificate and key paths are derived from this if not set individually.
`MCP_SSL_CERT_PATH`	`ssl_cert_path`	`<ssl_base_path>/server.pem`	Path to the TLS server certificate (PEM format).
`MCP_SSL_KEY_PATH`	`ssl_key_path`	`<ssl_base_path>/server.key`	Path to the TLS server private key.
`MCP_CA_CERT_PATH`	`ca_cert_path`	`<ssl_base_path>/ca.pem`	Path to the root CA certificate for client verification.
`MCP_CA_KEY_PATH`	`ca_key_path`	`<ssl_base_path>/ca.key`	Path to the CA private key.

Database settings

These variables configure the connection to the Vertica database.

Note

VERTICA_HOSTS accepts a comma-separated list of hostnames (for example, host1,host2,host3). Duplicate entries are automatically removed.

Environment variable	YAML key	Default value	Description
`VERTICA_HOST`	`vertica_host`	`localhost`	Vertica host to which the MCP server connects.
`VERTICA_PORT`	`vertica_port`	`5433`	Vertica server port.
`VERTICA_DBNAME`	`vertica_dbname`	(empty — server default)	Database name. If empty, the server's default database is used.
`VERTICA_SSLMODE`	`vertica_sslmode`	`disable`	TLS mode for the Vertica connection. Accepted values are `disable`, `require`, `verify-ca`, and `verify-full`. This setting is not supported by the native Vertica client (the default client); if you use the native client, set it to `disable`.
`MCP_USE_PG_CLIENT`	`use_pg_client`	`false`	Use the PostgreSQL wire protocol client instead of the native Vertica client.
`MCP_QUERY_TIMEOUT`	`query_timeout`	`20s`	Maximum duration for a single database query.
`MCP_MAX_QUERY_ROWS`	`max_query_rows`	`10000`	Maximum rows returned per query to prevent runaway result sets.
`MCP_USE_LOAD_BALANCING`	`use_load_balancing`	`false`	Enable connection load balancing for the Vertica native client.

Storage and secrets

These variables control how user credentials are stored and internal secrets are managed.

Note

MCP_JWT_SECRET is sensitive. Never store it in the YAML file. Always supply it as an environment variable.

Environment variable	YAML key	Default value	Description
`MCP_STORAGE_TYPE`	`storage_type`	`leveldb`	Backend used to store credentials. Accepted values are `leveldb` and `memory`.
`MCP_STORAGE_PATH`	`storage_path`	`/opt/vertica/config/mcp_server/userdb`	Filesystem path for the LevelDB database directory.
`MCP_STORAGE_ENCRYPTION_KEY`	(internal)	(derived from server key)	32-byte AES key for encrypting passwords at rest. If not set, a key is automatically derived from the server private key file using SHA-256.
`MCP_JWT_SECRET`	(internal)	(derived from server key)	HMAC secret used for signing and verifying API key JWTs. Derived from the server key at startup if not explicitly set.

VCluster server settings

These variables configure integration with VCluster server, which provides cluster-management tools.

Note

If the client certificate or private key at the configured paths is missing or invalid, VCluster tools are automatically disabled at startup.

Environment variable	YAML key	Default value	Description
`MCP_VCLUSTER_ENABLED`	`vcluster_enabled`	`true`	Enable or disable VCluster server tools.
`MCP_VCLUSTER_SERVER_URL`	`vcluster_server_url`	`https://localhost:8665`	Base URL of the VCluster server API.
`MCP_VCLUSTER_CERT_PATH`	`vcluster_cert_path`	`/opt/vertica/config/vcluster_server/admin.pem`	Path to the client certificate for authenticating with VCluster server.
`MCP_VCLUSTER_KEY_PATH`	`vcluster_key_path`	`/opt/vertica/config/vcluster_server/admin.key`	Path to the private key for the VCluster server client certificate.
`MCP_VCLUSTER_CA_CERT_PATH`	`vcluster_ca_cert_path`	`/opt/vertica/config/vcluster_server/ca.pem`	CA certificate for verifying the VCluster server TLS certificate. Leave this empty to use system defaults.
`MCP_VCLUSTER_SKIP_TLS_VERIFY`	`vcluster_skip_tls_verify`	`true`	When `true`, skips TLS server verification for VCluster connections. Enabled by default; set to `false` in production to enforce verification.
`MCP_VCLUSTER_NODES_CACHE_TTL`	`vcluster_nodes_cache_ttl`	`5m`	How long the node topology is cached before a refresh is triggered.

Job queue settings

These variables tune the server's internal asynchronous job queue for long-running operations.

Environment variable	YAML key	Default value	Description
`MCP_MAX_ACTIVE_JOBS`	`max_active_jobs`	`50`	Total queue capacity, including both pending and running jobs.
`MCP_MAX_RUNNING_JOBS`	`max_running_jobs`	`10`	Maximum number of concurrently running jobs.
`MCP_MAX_FINISHED_JOBS`	`max_finished_jobs`	`100000`	Maximum number of completed job records retained for status queries.
`MCP_FINISHED_JOB_RETENTION`	`finished_job_retention`	`240h` (10 days)	How long completed job records are kept before they are removed.
`MCP_QUERY_TREE_RETENTION`	`query_tree_retention`	`8760h` (1 year)	How long the generated query tree HTML files are kept before automatic cleanup.