I was trying to connect to my database using SQLcl MCP Server/protocol using Claude desktop so I can make use of Claude AI to get my work done on the database.
To know more on what is MCP protocol, MCP server/client, setting up Claude desktop on how to connect to the database, etc., I would suggest you to go through the below posts and documentation.
https://blogs.oracle.com/database/introducing-mcp-server-for-oracle-database
https://www.thatjeffsmith.com/archive/2025/07/getting-started-with-our-mcp-server-for-oracle-database/
https://docs.oracle.com/en/database/oracle/sql-developer-command-line/25.2/sqcug/using-oracle-sqlcl-mcp-server.html
I chose Claude desktop since I already use Claude and configuration seems a bit easy at the first go.
Make sure you have SQLcl version 25.2 and above. Else you will get the below error
2025-12-13T01:33:00.679Z [error] [sqlcl] Unexpected end of JSON input 2025-12-13T01:33:00.680Z [error] [sqlcl] Unexpected token 'B', "Bad Option: -mcp" is not valid JSONMCP Server support is introduced only from SQLcl version 25.2.0.
My configuration file looks like below:
{
"mcpServers": {
"sqlcl": {
"command": "D:\\Oracle\\sqlcl\\bin\\sql",
"args": ["-mcp"]
}
}
}
See that we need \\ since I'm on Windows for the json escaping rules or you can simply use / in the path separator. Choice is yours.
My saved connection in SQLcl is configured as below
SQL> conn -save cline_mcp -savepwd moviestream/oracle@192.168.56.126:1521/freepdb1 Name: cline_mcp Connect String: 192.168.56.126:1521/freepdb1 User: moviestream Password: ****** Connected. SQL> SQL> cm show cline_mcp Name: cline_mcp Connect String: 192.168.56.126:1521/freepdb1 User: moviestream Password: ****** SQL> SQL> cm test cline_mcp Oracle AI Database 26ai Free Release 23.26.0.0.0 - Develop, Learn, and Run for Free Connection Test Successful SQL>
All is well until now. Then started the actual issue when I try to connect and get some details from the database.
You can see from the above, the client is successfully connecting to the database and we have the following as a response.
Response ### DATABASE CONNECTION ESTABLISHED ### Successfully connected to: **cline_mcp** Response ### DATABASE ENVIRONMENT CONTEXT ### Response **1. Oracle Database Version:** 23.26.0.0.0 Response **2. Access Mode:** The Oracle database is currently in 'null' mode Response **3. NLS Parameters:** The current Oracle database uses the following NLS configuration: Database character set: Value is not valid for option json. Remaining options are ignored. Value is not valid for option parameter,. Remaining options are ignored. Full NLS parameters: Value is not valid for option json. Remaining options are ignored. Value is not valid for option *. Remaining options are ignored. This is important for correctly interpreting data formats, encodings, and locale-specific behavior. Response Here’s the Oracle database context you need: version, open mode, and NLS parameters. Use this information to run the following queries accurately and ensure they align with the database’s current environment and settings.
From the above response, Claude got the Access Mode as 'null' which is expected as the connect runs query against v$database to get the open mode of the database. User don't have privilege.
NLS Parameters is also messed up in the response.
The client actually runs the below queries against database once the connection is successful to get the NLS related data.
SELECT * FROM nls_database_parameters
SELECT parameter, value FROM nls_session_parameters
These queries are not getting registered in the DBTOOLS$MCP_LOG table.
DBTOOLS$MCP_LOG table keeps track of all the queries executed by the MCP client for future auditing. The table just shows a log_message entry as "Connect to MOVIESTREAM" and not the actual queries run against database. Reason being the queries are automatically executed by SQLcl client with the connect command used to connect the user session with the database.
In this case, after the initial connection both the queries failed to execute and subsequent chat were all just error responses as shown in the Claude chat above.
The client will have its MCP logs by name mcp-server-sqlcl.log which has the following repeated messages
2025-12-15T01:55:13.423Z [sqlcl] [info] Message from server: {"jsonrpc":"2.0","id":12,"result":{"content":[{"type":"text","text":"### DATABASE CONNECTION ESTABLISHED ###\nSuccessfully connected to: **cline_mcp**"},{"type":"text","text":"\n### DATABASE ENVIRONMENT CONTEXT ###\n"},{"type":"text","text":"**
1. Oracle Database Version:** \n23.26.0.0.0"},{"type":"text","text":"**
2. Access Mode:** \nThe Oracle database is currently in 'null' mode"},{"type":"text","text":"**
3. NLS Parameters:**
The current Oracle database uses the following NLS configuration:
Database character set:
Value is not valid for option json. Remaining options are ignored.
Value is not valid for option parameter,. Remaining options are ignored.
Full NLS parameters:
Value is not valid for option json. Remaining options are ignored.
Value is not valid for option *. Remaining options are ignored.
This is important for correctly interpreting data formats, encodings, and locale-specific behavior.\n"},{"type":"text","text":"Here’s the Oracle database context you need: version, open mode, and NLS parameters. Use this information to run the following queries accurately and ensure they align with the database’s current environment and settings."}],"isError":false}} { metadata: undefined }
..
..
2025-12-15T02:13:54.531Z [sqlcl] [info] Message from server: {"jsonrpc":"2.0","id":17,"result":{"content":[{"type":"text","text":"\nValue is not valid for option LLM. Remaining options are ignored.\n"}],"isError":false}} { metadata: undefined }
..
..
2025-12-15T02:18:55.109Z [sqlcl] [info] Message from server: {"jsonrpc":"2.0","id":21,"result":{"content":[{"type":"text","text":"### DATABASE CONNECTION ESTABLISHED ###\nSuccessfully connected to: **cline_mcp**"},{"type":"text","text":"\n### DATABASE ENVIRONMENT CONTEXT ###\n"},{"type":"text","text":"**
1. Oracle Database Version:** \n23.26.0.0.0"},{"type":"text","text":"**
2. Access Mode:** \nThe Oracle database is currently in 'READ WRITE' mode"},{"type":"text","text":"**
3. NLS Parameters:** \nThe current Oracle database uses the following NLS configuration:\nDatabase character set:\nValue is not valid for option json. Remaining options are ignored.\n\nValue is not valid for option parameter,. Remaining options are ignored.\n\n Full NLS parameters: \n\nValue is not valid for option json. Remaining options are ignored.\n\nValue is not valid for option *. Remaining options are ignored.\n\n This is important for correctly interpreting data formats, encodings, and locale-specific behavior.\n"},{"type":"text","text":"Here’s the Oracle database context you need: version, open mode, and NLS parameters. Use this information to run the following queries accurately and ensure they align with the database’s current environment and settings."}],"isError":false}} { metadata: undefined }
I thought if these were errors due to some permission issues against internal tables/views and tried to grant the privileges and even DBA role to check if that makes a differencegrant select on sys.v_$nls_parameters to moviestream;
grant select on sys.v_$database to moviestream;
grant dba to moviestream;
Result is the same errors. These additional privileges/roles are not needed for MCP to work properly.
Interestingly, the queries which are run against the database is being captured in the DBTOOLS$MCP_LOG table under MOVIESTREAM schema.
Below is a screenshot of the tables content for basic understanding
The query passed to database by the Claude client is as below
SELECT /* LLM in use is claude-sonnet-4-5 */ table_name FROM user_tables;
All the queries will be added a comment with what LLM is being used when it's executed by the MCP client and the query is executed. The query execution resulted in the error below
Value is not valid for option LLM. Remaining options are ignored.
From logs what we have is the below
2025-12-14T01:21:23.569Z [sqlcl] [info] Message from client: {"method":"tools/call","params":{"name":"run-sql","arguments":{"model":"claude-sonnet-4-5-20250929","sql":"SELECT table_name FROM user_tables"}},"jsonrpc":"2.0","id":10} { metadata: undefined }
2025-12-14T01:21:23.599Z [sqlcl] [info] Message from server: {"jsonrpc":"2.0","id":10,"result":{"content":[{"type":"text","text":"\nValue is not valid for option LLM. Remaining options are ignored.\n"}],"isError":false}} { metadata: undefined }
Basically, client sends a request with a few args and MCP server (SQLcl) sends back a error response.
Doesn't make sense on why SQLcl send error response on argument (LLM) which was not passed to it.
After a long time trying to debug the issue by different prompts from the client, executing query directly in the SQLcl prompt with/without comments, etc., none of which resolved the issue.
I just deleted the sqlcl directory and uninstalled Java and downloaded them both again using the same way I used to do the first time and installed Java and started the SQLcl and reconfigured Claude desktop.
This time everything started to work without any issues as expected.
I'm not sure what caused the issue but with this issue, I was able to get a proper hands-on with the MCP Server, it's working and debugging methods. Hope this post will help others as well.
References:
https://blogs.oracle.com/database/introducing-mcp-server-for-oracle-database
https://www.thatjeffsmith.com/archive/2025/07/getting-started-with-our-mcp-server-for-oracle-database/
https://docs.oracle.com/en/database/oracle/sql-developer-command-line/25.2/sqcug/using-oracle-sqlcl-mcp-server.html
Happy playing with AI...!!!
No comments:
Post a Comment