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
OPENAI_API_KEY spring.ai.openai.api-key	Your Azure OpenAI API key.	(none)
OPENAI_BASE_URL spring.ai.openai.base-url	Your Azure OpenAI endpoint URL.	(none)
OPENAI_CHAT_MODEL spring.ai.openai.chat.model	Deployment name of the chat model in your Azure OpenAI resource.	gpt-5.1
OPENAI_EMBEDDING_MODEL spring.ai.openai.embedding.model	Deployment name of the embedding model in your Azure OpenAI resource.	text-embedding-3-small

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.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

Subagents

Subagent delegation is active by default on the async chat path for the following task types: Timer, Manual, Windows, Linux/Unix, IBM i, and SAP. Use the following properties to control which subagents are enabled and tune advanced behavior.

Environment Variable / Property	Description	Default
STONEBRANCH_AI_AGENTS_CHAT_ALLOWED stonebranch.ai.agents.chat-allowed	Allow-list of subagents that may run on the chat path. All bundled subagent definitions load and are advertised to the orchestrator when their categories match the request; this list gates which ones can actually execute. A non-allow-listed delegation is refused at call time with a message directing the user to contact an administrator. Use * to allow all subagents, or provide a comma-separated list of subagent names. An empty list disables all subagent delegation.	See the Available Subagents table, below.
STONEBRANCH_AI_AGENTS_ANALYZE_ALLOWED stonebranch.ai.agents.analyze-allowed	Allow-list of subagents that may run on the analyze path. Empty by default; the analyze path exposes no subagents unless explicitly configured.	(none)

Available Subagents

The table below gives the names of each subagent available for each task type. By default, only six are enabled.

tip

The subagents not enabled by default are experimental.

Subagent Name	Task Type	Enabled by Default
create-file-monitor-task	Agent File Monitor
create-approval-task	Approval
create-email-task	Email
create-email-monitor-task	Email Monitor
create-ftp-task	File Transfer
create-ibmi-task	IBM i
create-unix-task	Linux/Unix
create-manual-task	Manual
create-peoplesoft-task	PeopleSoft
create-recurring-task	Recurring
create-remote-file-monitor-task	Remote File Monitor
create-sap-task	SAP
create-sql-task	SQL
create-stored-proc-task	Stored Procedure
create-system-monitor-task	System Monitor
create-task-monitor-task	Task Monitor
create-timer-task	Timer
create-ucmd-task	Universal Command
create-universal-monitor-task	Universal Monitor
create-variable-monitor-task	Variable Monitor
create-web-service-task	Web Service
create-windows-task	Windows
create-zos-task	z/OS
create-zos-monitor-task	z/OS Monitor

Advanced Settings

The following are advanced settings for controlling subagent execution limits and guardrails. The defaults are appropriate for most deployments.

Environment Variable / Property	Description	Default
AGENTS_MAX_DELEGATIONS_PER_SUBAGENT stonebranch.ai.agents.max-delegations-per-subagent	Maximum number of times the orchestrator may delegate to the same subagent within a single turn. Limits runaway re-delegation loops. A human-driven refinement (responding "Not yet" with a change note) resets the count.	2
AGENTS_MAX_TOOL_CALLS stonebranch.ai.agents.max-tool-calls	Within one subagent execution, the maximum number of times the subagent may call any single tool. A backstop against intra-execution tool loops.	5

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 Search

Environment Variable / Property	Description	Default
MCP_LIST_TASKS_DEFAULT_LIMIT stonebranch.ai-mcp.tools.list-tasks.default-limit	Maximum number of task definitions returned by a list_tasks call.	100

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