Chat with Your Oracle Database: SQLcl MCP + GitHub Copilot

Ask questions in plain English inside VS Code. Get SQL results back instantly — no copy-pasting, no switching tools.

The Problem: Too Many Switches

If you work with Oracle databases, you know the drill: write SQL in a text editor, copy it to SQL Developer or SQLcl, run it, then copy results back. Add an AI assistant into the mix and you get another window — one that can write SQL but has no way to actually run it against your database.

What if you could stay in VS Code, ask GitHub Copilot something like "Show me the top 10 customers by total order value", and see real results right in the chat?

You can. Oracle’s SQLcl includes a built-in Model Context Protocol (MCP) server, and GitHub Copilot in VS Code can talk to it. This article walks you through the setup and shows you how to query your Oracle database using natural language.

What You Need to Know

MCP in 30 Seconds

Model Context Protocol (MCP) is an open standard from Anthropic that lets AI assistants call external tools in a structured way. Think of it as a plug-and-play layer: the AI sends a request like "run this SQL", and a tool on your machine executes it and returns the result. The AI never talks to the database directly — it talks to the tool, and the tool talks to the database.

You (natural language) → Copilot (understands, writes SQL) → MCP → SQLcl → Oracle → results back

SQLcl’s Role

SQLcl is Oracle’s modern command-line interface for Oracle Database. It runs on your machine and can connect to Oracle Autonomous Database (or any Oracle DB) via JDBC. Starting with SQLcl 24.3, it ships with an embedded MCP server. When you run sql mcp, SQLcl listens on standard input/output — no separate server process, no ports to open.

Prerequisites

• Oracle Cloud Free account — oracle.com/cloud/free
• Oracle Autonomous Database (Always Free tier)
• SQLcl installed (brew install sqlcl on macOS)
• SQL Developer (for saving a named connection once)
• VS Code with GitHub Copilot (MCP support is generally available as of VS Code 1.102)

Step 1: Create and Configure Oracle Autonomous Database

1. In the OCI Console, go to Oracle Database → Autonomous Database and click Create Autonomous Database.

2. Set Always Free to ON, choose a database name (e.g. myappdb), and set an admin password.

3. After creation, go to Database connection → Download wallet. Extract the zip to a folder (e.g. ~/Downloads/Wallet_myappdb/).

4. Fix the wallet path in sqlnet.ora (OCI uses ? as a placeholder):

sed -i '' 's|DIRECTORY="?/network/admin"|DIRECTORY="/path/to/your/wallet"|' \
  /path/to/your/wallet/sqlnet.ora

5. Whitelist your IP if needed: Network → Access Control List → Add your public IP (e.g. 203.0.113.10/32).

Step 2: Install SQLcl and Verify the Connection

# macOS (Homebrew)
brew install sqlcl

# Verify
sql -v

Test the connection (replace paths and credentials):

TNS_ADMIN=~/Downloads/Wallet_myappdb \
  sql admin/<password>@myappdb_high

You should see Connected to: and a SQL> prompt. Type exit to leave.

Step 3: Save the Connection in SQL Developer

SQLcl and SQL Developer share a connection registry. Copilot will use connections by name, so you need to save it once:

1. Open SQL Developer.
2. Create a New Connection → Cloud Wallet.
3. Point to your wallet folder, enter username/password, choose the service (e.g. myappdb_high).
4. Name the connection (e.g. myappdb) and Test → Save.

The connection is stored in ~/.sqldeveloper/system*/o.jdeveloper.db.connection*/connections.xml. Copilot will look it up by that name — no credentials in chat.

Step 4: Add SQLcl MCP to VS Code

VS Code (and Copilot) use MCP servers defined in settings. Add SQLcl:

Option A: User settings

1. Open Settings (Cmd+, / Ctrl+,).
2. Search for MCP or go to GitHub Copilot → MCP servers.
3. Add the SQLcl server, or edit settings.json directly:

{
  "mcp": {
    "servers": {
      "sqlcl": {
        "type": "stdio",
        "command": "sql",
        "args": ["mcp"]
      }
    }
  }
}

Option B: Workspace config (.vscode/mcp.json)

For team projects, create or edit .vscode/mcp.json:

{
  "mcpServers": {
    "sqlcl": {
      "command": "sql",
      "args": ["mcp"]
    }
  }
}

Restart VS Code so the MCP server is loaded.

Step 5: Chat with Your Database

1. Open GitHub Copilot Chat (Cmd+Shift+I / Ctrl+Shift+I).
2. Ask in plain English, for example:
   • "Connect to myappdb and show me all tables"
   • "What columns does the ORDERS table have?"
   • "Find the top 10 customers by total order value"
   • "How many orders per month in the last year?"

Copilot will use the SQLcl MCP tools to connect, run SQL, and display results.

What Happens Under the Hood

When you ask a question:

1. Copilot understands the intent and decides which MCP tool to use (run-sql, schema-information, etc.).
2. Copilot generates the SQL.
3. MCP sends a JSON-RPC message to SQLcl over stdio: { "tool": "run-sql", "params": { "connection": "myappdb", "sql": "..." } }.
4. SQLcl looks up the saved connection, opens a JDBC session, runs the SQL against Oracle.
5. Oracle returns rows; SQLcl formats them as JSON and sends them back through MCP.
6. Copilot shows the results in the chat.

┌─────────────────────────────────────────────────────────┐
│  VS Code + GitHub Copilot Chat                          │
└─────────────────────┬───────────────────────────────────┘
                      │ MCP (JSON-RPC over stdio)
                      ▼
┌─────────────────────────────────────────────────────────┐
│  SQLcl MCP Server (sql mcp)                             │
│  Tools: connect, run-sql, schema-information, etc.      │
└─────────────────────┬───────────────────────────────────┘
                      │ JDBC / TLS
                      ▼
┌─────────────────────────────────────────────────────────┐
│  Oracle Autonomous Database                             │
└─────────────────────────────────────────────────────────┘

Example Prompts You Can Try

Large Results: Use run-sql-async

For queries that return many rows (e.g. full table scans on large tables), the standard run-sql tool can hit Copilot’s context limits. SQLcl provides run-sql-async, which submits the query, polls for completion, and fetches only the final result. Copilot will use this pattern when appropriate; you don’t need to change anything — just be aware that for big result sets, the flow may take a bit longer.

Security in a Nutshell

Troubleshooting

• "SQLcl not found" — Ensure sql is on your PATH (which sql). Add SQLcl’s bin directory to PATH if needed.
• "Connection refused" / ORA-12506 — Add your IP to the ADB Access Control List.
• "Wallet / SSL error" — Fix the DIRECTORY path in sqlnet.ora as in Step 1.
• MCP server not showing — Restart VS Code after editing MCP config. Ensure Copilot has permission to use MCP servers (some org policies disable it).

Summary

• MCP gives Copilot a standard way to call tools (like SQLcl) without custom integrations.
• SQLcl runs on your machine and talks to Oracle; sql mcp exposes an MCP server over stdio.
• Copilot understands natural language, generates SQL, and uses MCP to run it and show results.

Once you’ve set up the wallet, saved the connection in SQL Developer, and added SQLcl to VS Code’s MCP config, you can query your Oracle database in plain English from Copilot Chat — no more juggling windows.

Further Reading

• Oracle SQLcl — Download and documentation
• Model Context Protocol — MCP specification
• GitHub Copilot + MCP in VS Code — Official setup guide