Wallet and MCP Setup

Over the past month I was blessed to be able to speak at three regional Oracle user groups:

• the Rocky Mountain Oracle User Group (RMOUG)
• the SunCoast Oracle User Group (SOUG)
• the Utah Oracle User Group (UTOUG)

At each user group, a clear pattern stood out in the Q&A sessions. Most of the Oracle professionals I talked with knew very little about the Model Context Protocol (MCP), and even less about how to work with AI to obtain the multiplier effect with their jobs as Oracle professionals. That is the primary reason why I created this blog series. Over the next several posts, I'm going to focus on leveraging MCPs and connecting them to the tools every DBA already has available. This first part covers the foundation:

• What MCP actually is
• How to use SQLcl as an MCP server
• How to secure passwords
• How to use Claude Code to securely connect to Oracle AI Database 26ai

Large language models are only as useful as the context they can reach. For a DBA, that context lives inside the database, in the schemas, AWR, data dictionary, and application tables where the real work happens. Before MCP arrived, bridging an LLM to a database always felt unintuitive. We wrote custom adapters that aged the moment an API shifted, or we handed credentials to a process we did not fully trust, or we copied query results into the chat by hand and hoped nothing sensitive slipped through the cracks. MCP replaces those compromises with a single, well defined standard practice. In this first post, I will discuss the foundation that has to be set up before AI assistants can reach Oracle AI Database 26ai through MCP.

What MCP Actually Is

Model Context Protocol is an open standard that was first published by Anthropic in late 2024. It defines how AI assistants talk to external tools and data. Think of MCP as the gateway between AI and the Oracle database.

An MCP deployment has three roles. The host is the application the user interacts with, such as Claude Code, Claude Desktop, or an IDE plugin. The client is the component inside the host that actually speaks MCP, and for most users it is simply built in. The server is a separate process that exposes tools, resources, and prompts over the protocol. Most database vendors now ship an MCP server of their own. MySQL, Postgres, and plenty of others all have one, while Oracle's ships inside SQLcl.

Oracle ships an MCP server directly inside SQLcl 25.2 and later. Any host that speaks MCP can drive SQLcl, and by extension any Oracle AI Database 26ai instance SQLcl can reach.

Checklist Before You Start

A few things need to be in place before you begin. This section should be used as a checklist to confirm every item before you open SQLcl in Step 1. Installation is out of scope here because our focus is on MCP.

First, make sure to have SQLcl 25.2 or later with -mcp support. You can download Oracle SQLcl from the download page. Please verify the build before going further.

sql -V

The output should begin with SQLcl: Release 25.2 or higher. Anything earlier than 25.2 does not include the -mcp mode this article depends on.

Second, make sure you have Oracle AI Database 26ai reachable over SQL*Net from wherever you will run SQLcl. Port 1521 is the SQL*Net default and what this article uses for simplicity, but any port your listener is configured for will work the same way. If you do not already have an instance in front of you, installers and container images for the free developer release are catalogued on the Oracle Database Free page and its Get Started guide, and the official image lives in the Oracle Container Registry. Confirm the listener is reachable from the machine where SQLcl will run.

nc -zv <host> 1521

You need to substitute your listener's port if it is not 1521. A succeeded or open response means the network path is clear. If the test times out or reports no route to host, resolve this issue before anything else. The wallet and the MCP server will both fail silently on a blocked port.

You can install Claude Code with a single command: curl -fsSL https://claude.ai/install.sh | bash. Once you have a successful installation, make sure that Claude Code is available on your PATH and confirm the binary is resolvable.

claude --version

A version string means you are good to go to proceed. If the shell reports command not found, either the installer did not finish or the install directory is not on your PATH.

We need to provide a database account for AI to login with. We need to have tight guardrails around what the AI can see and/or do. As a general guideline, box in the AI and apply least privilege. Start read only with explicit grants on the schemas you are comfortable exposing, and layer anything else in only when the behavior has earned your trust. Confirm the user can log in with the credentials you plan to save into the wallet.

sql <user>/<password>@<host>:1521/<service>
SQL> select user from dual;

If the login fails here, the wallet save in Step 1 will also fail, and every downstream step will be chasing a phantom bug.

01Save a Named Connection With Its Password in the Wallet

Passwords have a tendancy to drift over time. They end up in shell history, in a config file that slips into a commit, in an environment variable that lingers after the process exits, or in a screenshot pasted into a chat. The goal of this step is to write the database password down exactly once, in encrypted form, so nothing else on your system ever has a reason to see it again.

SQLcl manages the credentials on the end user's machine, which means the password never moves between the MCP server and the model. It stays encrypted in the SQLcl auto login wallet, protected by filesystem permissions and Oracle's own SSO wallet format. The MCP server reaches the database through SQLcl rather than by handing the password across a process boundary, which keeps the credential out of reach of the model, out of reach of tool logs, and out of reach of the .mcp.json that Claude Code will later read.

SQLcl's conn -save command registers a named connection, and adding -savepwd stores the password inside that wallet. Every future connection, whether from the terminal or from the MCP server on the model's behalf, fetches the credential from the wallet by alias.

Let's launch SQLcl without logging in.

sql /nolog

In the example below, substitite your own user, password, host, and service.

SQL> conn -save selectai_free -savepwd SELECTAI_USER/Welcome#1234@172.20.1.102:1521/FREEPDB1

02Verify the Wallet Lookup

Once you confirmed that the alias is registered, you need to test that SQLcl can resolve the stored password. This validates that a new connection by name does not prompt for a password.

Here is a full worked example against the sandbox used for this article.

SQL> conn -save selectai_free -savepwd SELECTAI_USER/Welcome#1234@172.20.1.102:1521/FREEPDB1
Name:           selectai_free
Connect String: 172.20.1.102:1521/FREEPDB1
User:           SELECTAI_USER
Password:       ******
Connected.

SQL> cm list
.
├── SYSTEM_PROD
└── selectai_free

SQL> cm test selectai_free
Oracle AI Database 26ai Free Release 23.26.1.0.0 - Develop, Learn, and Run for Free
Connection Test Successful

SQL> disconnect
Disconnected from Oracle AI Database 26ai Free Release 23.26.1.0.0 - Develop, Learn, and Run for Free
Version 23.26.1.0.0

SQL> conn -name selectai_free
Connected.

SQL> show user
USER is "SELECTAI_USER"

SQL> select user from dual;

USER
________________
SELECTAI_USER

If conn -name returns Connected. without asking for a password, the wallet is configured correctly and the MCP server will reach the database the same way. You now have a connection that is addressable by name and free of inline secrets. That is what is necessary for the MCP server.

↳What SQLcl Actually Wrote to Disk

Everything you just created lives under ~/.dbtools/. This is the same tree used by SQL Developer Command Line and the rest of Oracle's Database Tools family, so if you have ever saved a SQL Developer connection on the same machine, you will see those here too.

Inside a SQLcl session, the canonical way to see what is saved is cm list, which walks the store and prints the aliases it finds.

SQL> cm list
.
├── SYSTEM_PROD
└── selectai_free

The relevant subdirectory is ~/.dbtools/connections/. Each saved connection gets its own directory named with a short random identifier, and inside that directory SQLcl writes exactly two files.

~/.dbtools/connections/
├── 9xdnBuDmRhZZHctTNrRrAg/
│   ├── credentials.sso
│   └── dbtools.properties
└── gIy4tW2qH5nZcNn4KlBLLg/
    ├── credentials.sso
    └── dbtools.properties

One directory per alias, and the two views match. SYSTEM_PROD and selectai_free from cm list correspond to the two subdirectories on disk.

The credentials.sso file is an Oracle auto login wallet in Oracle's standard .sso format. This is the encrypted password store. It is read only by your OS user thanks to 0600 permissions on the file and 0700 on the directory. This is what lets conn -name and sql -name log in without ever prompting.

The dbtools.properties file holds the connection metadata in plain text. Opening it shows what you saved and nothing sensitive.

name=selectai_free
type=ORACLE_DATABASE
connectionString=172.20.1.102\:1521/FREEPDB1
userName=SELECTAI_USER

The password is deliberately absent from this file. It only exists inside credentials.sso.

Because the directory names are opaque identifiers chosen by SQLcl, the mapping from alias to directory is maintained internally by the tool. Trust cm list and cm show <alias> for day to day inspection. Only reach for the filesystem when you are performing back ups or audits. If you want to back up the wallet, archive the entire ~/.dbtools/connections/ tree rather than trying to lift a single credentials.sso out of context. Do not commit any of this to git.

↳Connecting From the Shell

Once the alias exists and the wallet holds the password, you can skip the sql /nolog dance entirely. Invoke SQLcl with -name straight from the terminal and it opens already logged in.

% sql -name selectai_free
SQLcl: Release 25.4 Production on Wed Apr 15 02:28:36 2026

Copyright (c) 1982, 2026, Oracle.  All rights reserved.

Connected to:
Oracle AI Database 26ai Free Release 23.26.1.0.0 - Develop, Learn, and Run for Free
Version 23.26.1.0.0

SQL>

There is no password prompt, no host or port typed by hand, and nothing sensitive echoed to the terminal.

03Register the MCP Server with Claude Code

Claude Code reads MCP server definitions from ~/.claude.json at user scope, and from a .mcp.json at the root of whatever project directory you launch it from. Project scoped is the right default for a database, because it keeps the config alongside the work that actually uses it, and when you cd into a different project the server simply does not load.

Let's create a new .mcp.json file from your current project folder:

vim ~/Projects/dbaexpert.com/.mcp.json

Paste the following, save, and quit.

{
  "mcpServers": {
    "oracle-selectai-wallet": {
      "type": "stdio",
      "command": "sql",
      "args": ["-mcp"],
      "env": {}
    }
  }
}

There is no connect string or username in the json file. The SQLcl MCP server learns about your saved connections through the wallet we set up in Step 2, and the host picks one at runtime using the connect MCP tool.

Validate the JSON before you restart Claude Code, because invalid JSON here will prevent Claude Code from loading any server in this file. A clean OK means Claude Code will parse it on the next load.

% python3 -c 'import json,sys; json.load(open(sys.argv[1])); print("OK")' \
  /Users/vendome/Projects/dbaexpert.com/.mcp.json
OK

↳Start or Restart Claude Code

Claude Code discovers project scoped MCP servers at launch, not during a running session. To actually use oracle-selectai-wallet, the claude process has to connect to it at startup, which means a fresh session from this directory. If you wrote the .mcp.json from a terminal outside Claude Code, simply start one now.

claude

If you were already inside a Claude Code session when you created the file, the new server will not be listed yet because the config was loaded before the file existed. You need to quit the running session and come back in.

> /exit
% claude --resume

The same rule applies any time you change a server entry in .mcp.json. One thing to note, edits take effect on the next launch so you have to restart your session whenever you add, rename, or remove a server.

↳Confirm the Server Loads in Claude Code

Once Claude Code is running from this directory, run the /mcp command. The MCP servers panel should list oracle-selectai-wallet under Project with a green Connected badge, sourced from the file you just validated.

A few things in this panel are worth highlighting, because they illustrate how Claude Code stacks MCP servers from different places without any of them interfering with each other.

The oracle-selectai-wallet entry sits under Project, which is the project scoped definition we just wrote in .mcp.json. Drop into a different project directory and this server simply does not load, which is what you want for a config that is meaningful only when you are working on this blog.

Below it, under claude.ai, sit Gmail and Google Calendar. These are user scope MCPs configured through claude.ai rather than through a project file, so they follow you across every Claude Code session on this machine regardless of working directory. This MCP is useful for lightweight scheduling and email work, but their capabilities are deliberately narrow. The Calendar MCP lets you create, update, and delete events the way you would expect. The Gmail MCP can read, search, and draft, but cannot send out emails. The user must manually send and forward emails.

If you need the full Gmail functionality from an AI workflow, including send, label automation, and delegation, the path forward is the Google Workspace CLI (gws), maintained at github.com/googleworkspace/cli. Google made this available in March 2026 as a single command line tool that covers Drive, Gmail, Calendar, Sheets, Docs, Chat, and Admin.

↳A First Look in Action

Before we wrap up Part 1, here is what the stack looks like when you point Claude Code at the wallet backed MCP server and ask it a plain question. No SQL in the prompt, no credentials near the model, just the result the database returned.

Here is the prompt I sent into Claude Code.

❯ use oracle-selectai-wallet and show me the list of tables and row counts for each table

Claude Code threaded the question through the MCP server, queried the database, and returned this in the chat.

  Called oracle-selectai-wallet 2 times (ctrl+o to expand)

⏺ Connected as selectai_free (logged in directly as SELECTAI_USER). Tables owned by this user:

  ┌─────────────┬──────┐
  │    Table    │ Rows │
  ├─────────────┼──────┤
  │ COUNTRIES   │ 25   │
  ├─────────────┼──────┤
  │ DEPARTMENTS │ 27   │
  ├─────────────┼──────┤
  │ EMPLOYEES   │ 107  │
  ├─────────────┼──────┤
  │ JOBS        │ 19   │
  ├─────────────┼──────┤
  │ JOB_HISTORY │ 10   │
  ├─────────────┼──────┤
  │ LOCATIONS   │ 23   │
  ├─────────────┼──────┤
  │ REGIONS     │ 5    │
  └─────────────┴──────┘

  Total 7 tables, 216 rows

Two MCP tool calls, one clean table of results, and nothing in the conversation that could have leaked the password. That is the payoff of the wallet plus project scoped MCP combination we just built. Part 2 picks this thread up and walks through the tool calls one at a time.

Conclusion

You have a named SQLcl connection whose password lives in an encrypted auto login wallet, a project scoped .mcp.json that points a future Claude Code session at that wallet through the SQLcl MCP server, and two clean verification steps proving each half works before you involve an LLM at all. Come back for Part 2, where we dive deeper into the capabilities of MCP for Oracle professionals. We will build a real-world use case that calculates and charts consultant utilization entirely inside Oracle. Part 3 then takes the same pattern across database boundaries, chaining Oracle, MySQL, and Postgres MCP servers in a single Claude Code session so you can move and reconcile data between different engines from a chat window rather than a shell script.

The Series at a Glance

This is segment one of a six-part walkthrough of wiring Oracle AI Database 26ai to Claude Code over MCP. Each part stands on its own but builds on the one before.

1. Part 1 · Wallet and MCP Setup (this post). Build the credential boundary and the project scoped MCP config so the model can reach the database without ever seeing the password.
2. Part 2 · MCP in Practice for Oracle Professionals. A deeper look at what the Oracle SQLcl MCP server can actually do. Builds a real-world use case that calculates and charts consultant utilization entirely inside Oracle AI Database 26ai.
3. Part 3 · MCP for Data Architecture. Extends the schema with two new tables, documents them, audits the design through MCP, indexes the foreign keys it flags, reviews an older table against standards, and pulls the full entity relationship diagram back in one prompt.
4. Part 4 · MCP for Database Administration. Surveys the database, inventories every schema owner, creates a tablespace, moves tables and indexes online, audits archive log generation, and generates production-ready health check and RMAN backup scripts from a single English prompt.
5. Part 5 · MCP to Migrate Data Between Oracle and MySQL. Chains the Oracle and MySQL MCP servers in the same Claude Code session and walks through moving data across the boundary without leaving the chat window.
6. Part 6 · MCP to Migrate Data Between Oracle and Postgres. Same pattern as Part 5 with the Postgres MCP server, including the differences that matter for an Oracle DBA picking up Postgres for the first time.

Charles is an Oracle ACE Director, VMware vExpert, and author of over a dozen books in the Oracle ecosystem.