Having trouble with your AI Agent and running an Oracle Database connection with our SQLcl MCP Server?

It might look like this –

What happened? SQLcl can connect, and so can my SQL Developer VS Code extension???

The problem is that local MCP Servers appear in private environments, they do NOT inherit your system or user defined Environment Variables.

So, if you have a database connection that looks like this…

… You need a way to pass the location of the TNSNames.ora file to your Agent when SQLcl is run.

The solution

In your agent’s MCP configuration JSON file, simply add a line for the TNS_ADMIN environment variable.

Something like, this –

{
  "mcpServers": {
    "sqlcl": {
      "command": "/opt/sqlcl/25.4/sqlcl/bin/sql",
      "args": ["-mcp"],
      "env" : {"TNS_ADMIN" : "/Users/thatjeffsmith"}
    }
  }
}

{
  "mcpServers": {
    "sqlcl": {
      "command": "/opt/sqlcl/25.4/sqlcl/bin/sql",
      "args": ["-mcp"],
      "env" : {"TNS_ADMIN" : "/Users/thatjeffsmith"}
    }
  }
}

Line 6 is the important one.

Now, your agent MAY need to be restarted. Some of them will detect the change and reload, others will give you the option to force a reload, and some will make you restart the agent application itself.

Once you have ‘done the needful’, you will see something like this –

So now I can go back to my Agent, tell them I’ve fixed our stuff, and pick up where I left off!

I hope this helps! This came up more than a few times, which surprised me because we need to mention this explicitly in our Oracle SQLcl MCP Docs.