Operate, validate, and troubleshoot Oracle SQLcl MCP servers over stdio with 2026 best practices. Use when requests mention SQLcl MCP, sql -mcp startup, tools/list or tools/call validation, connection errors, timeout tuning, or client configuration for Cline/Claude Code/Claude Desktop.
Use this skill for operational work on SQLcl MCP server behavior, not for generic SQL tuning.
Run discovery before any test:
where.exe sql
Get-Command sql -ErrorAction SilentlyContinue
If SQLcl comes from VS Code Oracle extension on Windows, prefer extension-local paths:
...\.vscode\extensions\oracle.sql-developer-<ver>\dbtools\sqlcl\bin\sql.exe...\.vscode\extensions\oracle.sql-developer-<ver>\dbtools\jdk\bin\java.exeIf sql.exe -mcp fails with Unrecognized option: --add-opens, treat it as launcher/runtime mismatch. Launch through the embedded Java command:
& "<ext>\\dbtools\\jdk\\bin\\java.exe" `
"--add-modules" "ALL-DEFAULT" `
"--add-opens" "java.prefs/java.util.prefs=oracle.dbtools.win32" `
"--add-opens" "jdk.security.auth/com.sun.security.auth.module=oracle.dbtools.win32" `
"-Djava.net.useSystemProxies=true" `
"-p" "<ext>\\dbtools\\sqlcl\\launch" `
"-m" "oracle.dbtools.sqlcl.app" `
"-mcp"
Treat SQLcl MCP transport as newline-delimited JSON messages in this environment.
Do not assume Content-Length framing.
Send this sequence:
initializenotifications/initializedtools/listresources/listprompts/listAccept server readiness only if all are true:
initialize returns protocolVersion and serverInfo.tools/list returns at least one tool.Expect these SQLcl MCP tools (7):
list-connectionsconnectdisconnectrun-sqlclrun-sqlschema-informationrun-sql-asyncRun minimum behavioral checks:
list-connections and confirm non-crashing result.connect with a known invalid name and confirm deterministic error.run-sql without connection and confirm isError: true guidance.schema-information without connection and confirm connection-required error.Apply timeout and execution settings by client:
30-3600 s).scripts/configure-sqlcl-cline-timeout.ps1 in this repository.MCP_TOOL_TIMEOUT (milliseconds).300 s; optimize query shape instead of waiting longer.Prefer this execution strategy:
run-sql for deterministic SQL reads.run-sql-async for long-running queries (submit/status/results/cancel).run-sqlcl only for SQLcl command semantics that SQL cannot express directly.Use this order:
protocolVersion.run-sql-async.tools/list.list-connections.connection_name exactly (case sensitive behavior may apply).When reporting SQLcl MCP status, always include:
sql.exe vs embedded java).initialize, tools/list, resources/list, prompts/list).Use these files as local anchors for this project:
configs/sqlcl-mcp/cline_mcp_settings.template.jsonscripts/configure-sqlcl-cline-timeout.ps1IMPLEMENTATION_REPORT_SQLCL_TIMEOUT.mdSQLCL_MCP_TIMEOUT_REPORT.md