Dealing with TNS database connections with Oracle MCP (SQLcl)

Having problems with your AI Agent and getting an Oracle Database connection going with our SQLcl MCP Server?

That might look like this –

What’s happening? SQLcl can connect, and so can my SQL Developer VS Code extension???

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

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

… you need a way to convey the location of the TNSNames.ora file to your Agent when it sparks up SQLcl.

The solution

In your agent’s MCP config 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 a change and reload, others will give you the option to force a reload, and then some others will make you restart the agent application itself.

Once you’ve ‘done the needful,’ you should see something like this –

So now I can go back to my Agent, let it know I fixed our stuff, and to pick up where it left off!

I hope this helps! It’s come up more than a few times, which is a kick to my gut that we need to call this out explicitly in our Oracle SQLcl MCP Docs.