SQLcl MCP Server

The AI Optimizer natively supports the Oracle SQLcl MCP Server for Natural Language to SQL (NL2SQL) capabilities.

When SQLcl is available, its MCP server is automatically registered at startup as a proxy under the sqlcl namespace for the configured database aliases.

Requirements

1. SQLcl must be installed and the sql binary must be on the system PATH
2. At least one database must be configured with valid credentials (username, password, and DSN)

SQLcl Installation

Containers

The project's all-in-one image (src/Dockerfile) and server image (src/server/Dockerfile) already include SQLcl and Java. No additional SQLcl installation is required in the container or on the container host.

macOS

When running the AI Optimizer directly on macOS, install a supported Java runtime and the SQLcl Homebrew cask:

brew install --cask temurin@21
brew install --cask sqlcl

Add the following lines to ~/.zshrc so SQLcl can find Java and the AI Optimizer can find the sql binary when started from an interactive shell. The SQLcl path is resolved from the currently installed cask version:

export JAVA_HOME=$(/usr/libexec/java_home -v 21)
export PATH="$(brew --prefix)/Caskroom/sqlcl/$(brew list --versions --cask sqlcl | awk '{print $2}')/sqlcl/bin:$PATH"

Open a new terminal and verify the installation:

java -version
sql -version

Start or restart the AI Optimizer from an environment that inherits this PATH.

How It Works

At startup, the AI Optimizer:

1. Discovers the sql binary on the system path
2. Creates connection store entries for each configured database
3. Launches SQLcl as a child process on the AI Optimizer Server using stdio transport
4. Mounts the SQLcl MCP server as a proxy, making NL2SQL tools available alongside the built-in tools

SQLcl commands run on the AI Optimizer Server. External MCP clients send requests to that server.

SQLcl Home Directory

The SQLcl connection store is created in a temporary directory by default. The AI Optimizer uses AIO_SQLCL_HOME first, then SQLCL_HOME.

Set AIO_SQLCL_HOME to a dedicated writable directory before starting the AI Optimizer. The Server rebuilds this directory when it registers or refreshes the SQLcl connections:

export AIO_SQLCL_HOME=/path/to/ai-optimizer/sqlcl

SQLcl Restrict Level

The AI Optimizer Server starts SQLcl with -R and the resolved AIO_SQLCL_MCP_LEVEL value. The default level, 4, applies SQLcl's strongest restrictions to host commands, scripts, and configuration-changing commands.

Set AIO_SQLCL_MCP_LEVEL to an integer from 0 to 4 before starting the Server. Use the highest level that supports the required SQLcl commands:

export AIO_SQLCL_MCP_LEVEL=4

The Server validates this range at startup. Oracle Database privileges continue to control the SQL statements available to the connection. Configure NL2SQL connections with database accounts that have the required permissions.