SQLcl MCP Server

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

When SQLcl is available and databases are configured, the SQLcl MCP server is automatically registered at startup as a proxy under the sqlcl namespace.

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 and do not run the sql binary themselves.

SQLcl Home Directory

The SQLcl connection store is created in a temporary directory unless a SQLcl home is configured. The AI Optimizer uses AIO_SQLCL_HOME first, then SQLCL_HOME.

To choose the location explicitly, set AIO_SQLCL_HOME to a writable directory before starting the AI Optimizer:

export AIO_SQLCL_HOME=/path/to/sqlcl/home

SQLcl Restrict Level

The AI Optimizer Server starts SQLcl with -R and the resolved AIO_SQLCL_MCP_LEVEL value. The default restrict level is 4, which blocks host commands, scripts, and configuration-changing SQLcl commands.

Set AIO_SQLCL_MCP_LEVEL to an integer from 0 to 4 before starting the server when a lower level is required:

export AIO_SQLCL_MCP_LEVEL=4

Values outside this range prevent the server from starting. The restrict level does not change Oracle Database privileges. Configure NL2SQL connections with database accounts that have only the required permissions.

SQLcl Not Found?

If SQLcl is not installed or the sql binary is not on the system path, the NL2SQL functionality will be unavailable. The AI Optimizer will log a warning and continue without it.