Configuration

This page provides a reference of configuration options for the AI Service and AI MCP Server. Options can be set as environment variables (in setenv.bat / setenv.sh) or as properties in an application.yml file placed in the Tomcat instance's conf folder.

AI Service Configuration

Database Connection

Environment Variable / Property	Description	Default
DATASOURCE_VECTORSTORE_PGVECTOR_URL spring.datasource-vectorstore-pgvector.url	JDBC URL for the PGVector database.	jdbc:postgresql://localhost:5432/ai_db
DATASOURCE_VECTORSTORE_PGVECTOR_USER spring.datasource-vectorstore-pgvector.username	Database username.	postgres
DATASOURCE_VECTORSTORE_PGVECTOR_PASSWORD spring.datasource-vectorstore-pgvector.password	Database password.	(none)

Azure OpenAI

Environment Variable / Property	Description	Default
CHAT_PROVIDER spring.ai.chat.provider	Chat model provider. Only azure_openai is officially supported.	azure_openai
EMBEDDING_PROVIDER spring.ai.embedding.provider	Embedding model provider. Only azure_openai is officially supported.	azure_openai
AZURE_OPENAI_API_KEY spring.ai.azure.openai.api-key	Your Azure OpenAI API key.	(none)
AZURE_OPENAI_ENDPOINT spring.ai.azure.openai.endpoint	Your Azure OpenAI endpoint URL.	(none)
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME spring.ai.azure.openai.chat.options.deployment-name	Deployment name of the chat model in your Azure OpenAI resource.	gpt-4.1
AZURE_OPENAI_EMBEDDING_DEPLOYMENT_NAME spring.ai.azure.openai.embedding.options.deployment-name	Deployment name of the embedding model in your Azure OpenAI resource.	text-embedding-3-small
AZURE_HTTP_LOG_DETAIL_LEVEL spring.ai.azure.openai.http-log-detail-level	HTTP log detail level for Azure SDK requests. Valid values: NONE, BASIC, HEADERS, BODY_AND_HEADERS.	BASIC

AI MCP Server Connection

Environment Variable / Property	Description	Default
MCP_SERVER_URL spring.ai.mcp.client.streamable-http.connections.ai-mcp.url	URL of the AI MCP Server.	http://localhost:8082/ai-mcp

Logging

See Logging for additional details on logging configuration.

Environment Variable / Property	Description	Default
LOG_FILE_NAME logging.file.name	Full path to the log file. Overrides the auto-resolved default. Set to empty to disable file logging.	${catalina.base}/logs/ai.log (external Tomcat)
LOG_THRESHOLD_CONSOLE logging.threshold.console	Minimum log level for console output. Default OFF (file only). Set to a level such as INFO or DEBUG to enable console logging.	OFF
LOGGING_LEVEL_COM_STONEBRANCH_AI logging.level.com.stonebranch.ai	Log level for Stonebranch AI components.	INFO
LOGGING_LEVEL_SPRING logging.level.org.springframework	Log level for Spring Framework components.	INFO
LOGGING_LEVEL_SPRING_AI logging.level.org.springframework.ai	Log level for Spring AI components. Inherits from LOGGING_LEVEL_SPRING if not set.	Inherits LOGGING_LEVEL_SPRING
LOGGING_LEVEL_AZURE_HTTP logging.level.getChatCompletionsSync / logging.level.getEmbeddingsSync	Log level for Azure SDK HTTP operations (chat completions and embeddings).	INFO
logging.logback.rollingpolicy.max-file-size	Maximum log file size before the file is rolled.	10MB
logging.logback.rollingpolicy.max-history	Number of days to retain archived log files.	7
logging.logback.rollingpolicy.total-size-cap	Maximum total size of all archived log files. 0B means unlimited.	0B
logging.logback.rollingpolicy.clean-history-on-start	Whether to delete archived log files exceeding max-history on startup.	true

Authentication

See Setting Up the AI Service - Enable Authentication for setup instructions and details.

Environment Variable / Property	Description	Default
API_KEY_AUTH_ENABLED stonebranch.ai.authentication.api-key.enabled	Enable or disable API key authentication globally. Strongly recommended for production.	false
UC_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.default.keys	API key(s) for the default UC environment. Use for single-instance or simple deployments. Accepts a comma-separated list to support key rotation.	(none)
UC_PROD_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.prod.keys	API key(s) for the production UC environment.	(none)
UC_STAGING_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.staging.keys	API key(s) for the staging UC environment.	(none)
UC_DEV_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.dev.keys	API key(s) for the development UC environment.	(none)
UC_QA_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.qa.keys	API key(s) for the QA/testing UC environment.	(none)
UC_DR_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.dr.keys	API key(s) for the disaster recovery UC environment.	(none)
UC_TRAINING_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.training.keys	API key(s) for the training UC environment.	(none)
UC_DEMO_API_KEYS stonebranch.ai.authentication.api-key.applications.uc.environments.demo.keys	API key(s) for the demo UC environment.	(none)

Encryption

See Setting Up the AI Service - Enable Property Encryption for setup instructions and details.

Environment Variable / Property	Description	Default
KEYRING_FILE stonebranch.ai.keyring.file	Path to keyring.json on the filesystem. If set, takes precedence over KEYRING_BASE64.	(none)
KEYRING_BASE64 stonebranch.ai.keyring.base64	Base64-encoded keyring JSON content. Used when storing the keyring file on disk is not practical (for example, in containerized environments).	(none)

Tools

See Tools for a full list of available tools and guidance on configuring the tool whitelist.

Environment Variable / Property	Description	Default
STONEBRANCH_AI_TOOLS_CHAT_ALLOWED stonebranch.ai.tools.chat-allowed	List of tools available to the AI Assistant. Use * to allow all tools. When using an environment variable, provide a comma-separated list of tool names.	* (all tools)
STONEBRANCH_AI_TOOLS_ANALYZE_ALLOWED stonebranch.ai.tools.analyze-allowed	List of tools available to AI Analyze. When using an environment variable, provide a comma-separated list of tool names.	See Tools

AI MCP Server Configuration

Universal Controller Connection

Environment Variable / Property	Description	Default
UC_API_BASE_URLS stonebranch.ai-mcp.uc.base-urls	Base URL(s) of the Universal Controller web application. Single URL (single node or load balancer): http://uc-server:8080/uc Multiple URLs (HA cluster nodes or multiple environments): ha1:8080-uc@https://ha1:8080/uc|ha2:8080-uc@https://ha2:8080/uc In multi-node configurations, each URL is prefixed with a cluster node ID. Requests are routed to the matching node based on the node ID in the request.	http://localhost:8080/uc

CORS

Environment Variable / Property	Description	Default
MCP_CORS_ENABLED stonebranch.ai-mcp.cors.enabled	Enable or disable CORS handling.	true
MCP_CORS_ALLOWED_ORIGINS stonebranch.ai-mcp.cors.allowed-origins	Comma-separated list of allowed origins. The default permits any localhost port, which is suitable for development. For production, restrict to specific trusted origins (for example, https://your-app.com).	http://localhost:*,http://127.0.0.1:*

Task Instance Search

The following options configure the default behavior of task instance list tools (list_task_instances_by_name, list_task_instances_by_task_name, list_task_instances_by_task_id). They do not apply to workflow-scoped tools.

Environment Variable / Property	Description	Default
MCP_LIST_TASK_INSTANCES_DEFAULT_TIME_WINDOW stonebranch.ai-mcp.tools.list-task-instances.default-time-window	Default time window applied when the AI does not specify one. Uses duration format (e.g. 48h, 7d).	48h
MCP_LIST_TASK_INSTANCES_MAX_TIME_WINDOW stonebranch.ai-mcp.tools.list-task-instances.max-time-window	Maximum allowed time window. Requests exceeding this limit are capped.	7d
MCP_LIST_TASK_INSTANCES_DEFAULT_LIMIT stonebranch.ai-mcp.tools.list-task-instances.default-limit	Maximum number of results returned per query.	50

Logging

See Logging for additional details on logging configuration.

Environment Variable / Property	Description	Default
LOG_FILE_NAME logging.file.name	Full path to the log file. Overrides the auto-resolved default. Set to empty to disable file logging.	${catalina.base}/logs/ai-mcp.log (external Tomcat)
LOG_THRESHOLD_CONSOLE logging.threshold.console	Minimum log level for console output. Default OFF (file only). Set to a level such as INFO or DEBUG to enable console logging.	OFF
LOGGING_LEVEL_COM_STONEBRANCH_AI logging.level.com.stonebranch.ai	Log level for Stonebranch AI components.	INFO
LOGGING_LEVEL_SPRING logging.level.org.springframework	Log level for Spring Framework components.	INFO
LOGGING_LEVEL_SPRING_AI logging.level.org.springframework.ai	Log level for Spring AI components. Inherits from LOGGING_LEVEL_SPRING if not set.	Inherits LOGGING_LEVEL_SPRING
logging.logback.rollingpolicy.max-file-size	Maximum log file size before the file is rolled.	10MB
logging.logback.rollingpolicy.max-history	Number of days to retain archived log files.	7
logging.logback.rollingpolicy.total-size-cap	Maximum total size of all archived log files. 0B means unlimited.	0B
logging.logback.rollingpolicy.clean-history-on-start	Whether to delete archived log files exceeding max-history on startup.	true