The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external tools and services. Amazon Q Developer CLI now supports MCP, allowing you to extend Q's capabilities by connecting it to custom tools and services.
Oracle SQLcl supports MCP-based communication. After establishing a connection, Amazon Q Developer CLI can use natural language to perform the full range of database operations. This includes executing SQL queries, invoking PL/SQL procedures, and running SQLcl-specific commands.
1. Prerequisites:
- Valid db connection
- SQLcl version (version 25.2.0 or higher)
sql -s donghua/ComplexPassword@localhost:1521/freepdb1 <<EOD
select banner from v\$version;
EOD
Sample output:
BANNER
__________________________________________________________________________________
Oracle Database 23ai Free Release 23.0.0.0.0 - Develop, Learn, and Run for Free
sqlcl -version
Sample output:
SQLcl: Release 25.2.2.0 Production Build: 25.2.2.199.0918
2. Configure Save DB Connections
conn -save qcli_mcp -savepwd donghua/ComplexPassword@//localhost:1521/freepdb1
Sample output:
mylocalhost % sql /nolog
SQLcl: Release 25.2 Production on Mon Aug 18 12:37:12 2025
Copyright (c) 1982, 2025, Oracle. All rights reserved.
SQL> conn -save qcli_mcp -savepwd donghua/ComplexPassword@//localhost:1521/freepdb1
Name: qcli_mcp
Connect String: //localhost:1521/freepdb1
User: donghua
Password: ******
Connected.
SQL>
SQL> exit
Disconnected from Oracle Database 23ai Free Release 23.0.0.0.0 - Develop, Learn, and Run for Free
Version 23.8.0.25.04
mylocalhost % sql -name qcli_mcp
SQLcl: Release 25.2 Production on Mon Aug 18 12:36:12 2025
Copyright (c) 1982, 2025, Oracle. All rights reserved.
Connected to:
Oracle Database 23ai Free Release 23.0.0.0.0 - Develop, Learn, and Run for Free
Version 23.8.0.25.04
Optionally, you can list these saved connections and remove unnecessary connections using the following commands:
cm list
cm delete -conn=qcli_mcp
3. Configure Q Developer CLI to integrate with SQLcl MCP
# Add MCP Server
qchat mcp add --name sqlci_mcp --command "sql" --args "-mcp"
# List all configured MCP Servers
qchat mcp list
# Check the status of the MCP server
qchat mcp status --name sqlci_mcp
Sample output:
mylocalhost % q mcp add --name sqlci_mcp --command "sql" --args "-mcp"
To learn more about MCP safety, see https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-security.html
✓ Added MCP server 'sqlci_mcp' to 📄 workspace
mylocalhost % qchat mcp status --name sqlci_mcp
─────────────
Scope : 📄 workspace
File : /Users/donghual/.amazonq/mcp.json
Command : sql
Timeout : 120000 ms
Disabled: false
Env Vars:
4. Sample Examples Working with MCP
- Connect to qcli_mcp using SQLcl and retrieve Oracle database name
- Get total database size
- Get the DDL for table DBTOOLS$MCP_LOG
- List sample records in DBTOOLS$MCP_LOG and format as JSON
mylocalhost % q chat
⚠ sqlci_mcp has loaded in 0.88 s with the following warning:
The following tool names are changed:
- sqlci_mcp___run-sqlcl -> sqlci_mcp___runsqlcl
- sqlci_mcp___run-sql -> sqlci_mcp___runsql
- sqlci_mcp___list-connections -> sqlci_mcp___listconnections
⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⢀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠘⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀⢸⣿⣿
⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀⠀⢸⣿⡿
⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
⠚⠛⠋⠀⠀⠀⠀⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀⠀⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠿⢿⡧
╭─────────────────────────────── Did you know? ────────────────────────────────╮
│ │
│ You can enable custom tools with MCP servers. Learn more with │
│ /help │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
/help all commands • ctrl + j new lines • ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-4-sonnet
> connect to qcli_mcp using sqlcl, and retrieve oracle database name
> I'll help you connect to the qcli_mcp connection using SQLcl and retrieve the Oracle database name.
First, let me connect to the qcli_mcp connection:
🛠️ Using tool: connect from mcp server sqlci_mcp
⋮
● Running connect with the param:
⋮ {
⋮ "arguments": {
⋮ "connection_name": "qcli_mcp",
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022"
⋮ },
⋮ "name": "connect"
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:
> t
⋮ }
⋮
● Completed in 1.281s
> Great! I've successfully connected to the qcli_mcp connection. Now let me retrieve the Oracle database name by
querying the database:
🛠️ Using tool: run-sql from mcp server sqlci_mcp
⋮
● Running run-sql with the param:
⋮ {
⋮ "arguments": {
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022",
⋮ "sql": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ name FROM v$database"
⋮ },
⋮ "name": "run-sql"
Allow this action? Use 't' to trust (always allow) this tool for the session. [y/n/t]:
> t
⋮ }
⋮
● Completed in 0.40s
> Perfect! I've successfully connected to the Oracle database using the qcli_mcp connection and retrieved the
database name.
Connection Details:
• Successfully connected to: qcli_mcp
• Oracle Database Version: 23.0.0.0.0
• Database Name: FREE
• Database Mode: READ WRITE
• Character Set: AL32UTF8
The Oracle database name is FREE, which indicates this is likely an Oracle Database Free edition (formerly Oracle XE)
.
> get total database size
> I'll retrieve the total database size for you. Let me query the database to get this information:
🛠️ Using tool: run-sql (trusted) from mcp server sqlci_mcp
⋮
● Running run-sql with the param:
⋮ {
⋮ "arguments": {
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022",
⋮ "sql": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ \n ROUND(SUM(bytes)/1024/1024/1024, 2) AS \"Total Size (GB)\",\n ROUND(SUM(bytes)/1024/1024, 2) AS \"Total Size (MB)\"\nFROM dba_data_files\nUNION ALL\nSELECT \n ROUND(SUM(bytes)/1024/1024/1024, 2) AS \"Total Size (GB)\",\n ROUND(SUM(bytes)/1024/1024, 2) AS \"Total Size (MB)\"\nFROM dba_temp_files"
⋮ },
⋮ "name": "run-sql"
⋮ }
⋮
● Completed in 0.79s
> Let me also get a more detailed breakdown of the database size including different file types:
🛠️ Using tool: run-sql (trusted) from mcp server sqlci_mcp
⋮
● Running run-sql with the param:
⋮ {
⋮ "arguments": {
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022",
⋮ "sql": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ \n 'Data Files' AS file_type,\n COUNT(*) AS file_count,\n ROUND(SUM(bytes)/1024/1024, 2) AS size_mb,\n ROUND(SUM(bytes)/1024/1024/1024, 2) AS size_gb\nFROM dba_data_files\nUNION ALL\nSELECT \n 'Temp Files' AS file_type,\n COUNT(*) AS file_count,\n ROUND(SUM(bytes)/1024/1024, 2) AS size_mb,\n ROUND(SUM(bytes)/1024/1024/1024, 2) AS size_gb\nFROM dba_temp_files\nUNION ALL\nSELECT \n 'Redo Log Files' AS file_type,\n COUNT(*) AS file_count,\n ROUND(SUM(bytes)/1024/1024, 2) AS size_mb,\n ROUND(SUM(bytes)/1024/1024/1024, 2) AS size_gb\nFROM v$log"
⋮ },
⋮ "name": "run-sql"
⋮ }
⋮
● Completed in 0.35s
> Total Database Size Summary:
Overall Database Size:
• **Data Files**: 807 MB (0.79 GB) across 4 files
• **Temp Files**: 20 MB (0.02 GB) across 1 file
• **Redo Log Files**: 600 MB (0.59 GB) across 3 files
Total Combined Size: ~1.4 GB (1,427 MB)
Breakdown:
• **Data Files (807 MB)**: Contains the actual database data, indexes, and system information
• **Temporary Files (20 MB)**: Used for temporary operations like sorting and joins
• **Redo Log Files (600 MB)**: Used for transaction logging and recovery
This is a relatively small Oracle FREE database, which is consistent with the Oracle Database Free edition that
typically has storage limitations compared to enterprise editions.
> get the ddl for table DBTOOLS$MCP_LOG
> I'll retrieve the DDL for the DBTOOLS$MCP_LOG table for you:
🛠️ Using tool: run-sql (trusted) from mcp server sqlci_mcp
⋮
● Running run-sql with the param:
⋮ {
⋮ "arguments": {
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022",
⋮ "sql": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ \n DBMS_METADATA.GET_DDL('TABLE', 'DBTOOLS$MCP_LOG', 'DONGHUA') AS ddl\nFROM dual"
⋮ },
⋮ "name": "run-sql"
⋮ }
⋮
● Completed in 6.12s
> Let me also get the column details in a more readable format:
🛠️ Using tool: run-sql (trusted) from mcp server sqlci_mcp
⋮
● Running run-sql with the param:
⋮ {
⋮ "arguments": {
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022",
⋮ "sql": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ \n column_name,\n data_type,\n data_length,\n data_precision,\n data_scale,\n nullable,\n data_default,\n column_id\nFROM dba_tab_columns \nWHERE owner = 'DONGHUA' \nAND table_name = 'DBTOOLS$MCP_LOG'\nORDER BY column_id"
⋮ },
⋮ "name": "run-sql"
⋮ }
⋮
● Completed in 0.125s
> DDL for DBTOOLS$MCP_LOG Table:
This appears to be a logging table for MCP (Model Context Protocol) operations. Here's the cleaned-up structure:
Table Structure:
sql
CREATE TABLE "DONGHUA"."DBTOOLS$MCP_LOG" (
"ID" NUMBER GENERATED BY DEFAULT AS IDENTITY
MINVALUE 1 MAXVALUE 9999999999999999999999999999
INCREMENT BY 1 START WITH 1 CACHE 20
NOORDER NOCYCLE NOKEEP NOSCALE NOT NULL,
"MCP_CLIENT" VARCHAR2(200) NOT NULL,
"MODEL" VARCHAR2(200),
"END_POINT_TYPE" VARCHAR2(12),
"END_POINT_NAME" VARCHAR2(100) NOT NULL,
"LOG_MESSAGE" CLOB DEFAULT NULL,
"CREATED_ON" TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP NOT NULL,
"CREATED_BY" VARCHAR2(100) DEFAULT USER NOT NULL,
"UPDATED_ON" TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
"UPDATED_BY" VARCHAR2(100) DEFAULT USER,
CONSTRAINT check_endpoint_type
CHECK (end_point_type IN ('tool', 'prompt', 'resource', 'sample', 'root', 'transport')),
PRIMARY KEY ("ID")
) TABLESPACE "USERS";
Column Details:
• **ID**: Auto-incrementing primary key using Oracle 12c+ IDENTITY column
• **MCP_CLIENT**: Name/version of the MCP client (200 chars, required)
• **MODEL**: LLM model name/version (200 chars, optional)
• **END_POINT_TYPE**: Type of endpoint (limited to specific values via CHECK constraint)
• **END_POINT_NAME**: Name of the endpoint (100 chars, required)
• **LOG_MESSAGE**: CLOB for storing log messages (up to 4000 chars in-row)
• **CREATED_ON/CREATED_BY**: Audit fields for creation (auto-populated)
• **UPDATED_ON/UPDATED_BY**: Audit fields for updates (auto-populated)
This table is designed to log MCP operations and interactions, which explains why it exists in your Oracle database
when using the MCP-enabled SQLcl tools.
> DDL for DBTOOLS$MCP_LOG Table:
> I already provided the DDL for the DBTOOLS$MCP_LOG table in my previous response. Here's the complete DDL
structure again:
DDL for DBTOOLS$MCP_LOG Table:
sql
CREATE TABLE "DONGHUA"."DBTOOLS$MCP_LOG" (
"ID" NUMBER GENERATED BY DEFAULT AS IDENTITY
MINVALUE 1 MAXVALUE 9999999999999999999999999999
INCREMENT BY 1 START WITH 1 CACHE 20
NOORDER NOCYCLE NOKEEP NOSCALE NOT NULL,
"MCP_CLIENT" VARCHAR2(200) NOT NULL,
"MODEL" VARCHAR2(200),
"END_POINT_TYPE" VARCHAR2(12),
"END_POINT_NAME" VARCHAR2(100) NOT NULL,
"LOG_MESSAGE" CLOB DEFAULT NULL,
"CREATED_ON" TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP NOT NULL,
"CREATED_BY" VARCHAR2(100) DEFAULT USER NOT NULL,
"UPDATED_ON" TIMESTAMP(6) DEFAULT CURRENT_TIMESTAMP,
"UPDATED_BY" VARCHAR2(100) DEFAULT USER,
CONSTRAINT check_endpoint_type
CHECK (end_point_type IN ('tool', 'prompt', 'resource', 'sample', 'root', 'transport')),
PRIMARY KEY ("ID")
) TABLESPACE "USERS";
Key Features:
• **Identity Column**: Auto-incrementing ID using Oracle's IDENTITY feature
• **MCP Logging**: Designed to track Model Context Protocol operations
• **Audit Trail**: Automatic timestamp and user tracking
• **Flexible Storage**: CLOB field for variable-length log messages
• **Data Validation**: CHECK constraint on endpoint types
This table serves as a logging mechanism for MCP operations in your Oracle database environment.
> list sample records in DBTOOLS$MCP_LOG and format in json
> I'll retrieve sample records from the DBTOOLS$MCP_LOG table and format them as JSON:
🛠️ Using tool: run-sql (trusted) from mcp server sqlci_mcp
⋮
● Running run-sql with the param:
⋮ {
⋮ "arguments": {
⋮ "mcp_client": "Amazon Q CLI",
⋮ "model": "claude-3-5-sonnet-20241022",
⋮ "sql": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ \n JSON_OBJECT(\n 'id' VALUE id,\n 'mcp_client' VALUE mcp_client,\n 'model' VALUE model,\n 'end_point_type' VALUE end_point_type,\n 'end_point_name' VALUE end_point_name,\n 'log_message' VALUE SUBSTR(log_message, 1, 500),\n 'created_on' VALUE TO_CHAR(created_on, 'YYYY-MM-DD HH24:MI:SS'),\n 'created_by' VALUE created_by,\n 'updated_on' VALUE TO_CHAR(updated_on, 'YYYY-MM-DD HH24:MI:SS'),\n 'updated_by' VALUE updated_by\n FORMAT JSON\n ) AS json_record\nFROM donghua.dbtools$mcp_log \nORDER BY created_on DESC\nFETCH FIRST 10 ROWS ONLY"
⋮ },
⋮ "name": "run-sql"
⋮ }
⋮
● Completed in 0.52s
> Sample Records from DBTOOLS$MCP_LOG (JSON Format):
Here are the 10 most recent log entries showing all the SQL queries we've executed during our session:
json
[
{
"id": 23,
"mcp_client": "Amazon Q CLI",
"model": "claude-3-5-sonnet-20241022",
"end_point_type": "tool",
"end_point_name": "run-sql",
"log_message": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ JSON_OBJECT(...)",
"created_on": "2025-08-18 13:02:57",
"created_by": "DONGHUA",
"updated_on": "2025-08-18 13:02:57",
"updated_by": "DONGHUA"
},
{
"id": 22,
"mcp_client": "Amazon Q CLI",
"model": "claude-3-5-sonnet-20241022",
"end_point_type": "tool",
"end_point_name": "run-sql",
"log_message": "SELECT /* LLM in use is claude-3-5-sonnet-20241022 */ SYSDATE FROM dual",
"created_on": "2025-08-18 13:01:49",
"created_by": "DONGHUA",
"updated_on": "2025-08-18 13:01:49",
"updated_by": "DONGHUA"
},
{
"id": 21,
"mcp_client": "Amazon Q CLI",
"model": "claude-3-5-sonnet-20241022",
"end_point_type": "tool",
"end_point_name": "run-sql",
"log_message": "SELECT column_name, data_type... FROM dba_tab_columns WHERE owner = 'DONGHUA'...",
"created_on": "2025-08-18 13:00:53",
"created_by": "DONGHUA",
"updated_on": "2025-08-18 13:00:53",
"updated_by": "DONGHUA"
}
]
Key Observations:
1. Complete Audit Trail: Every SQL query executed through the MCP interface is logged
2. Session Tracking: All entries show "Amazon Q CLI" as the MCP client and "claude-3-5-sonnet-20241022" as the model
3. Query History: The log captures our entire conversation history including:
• Database size queries
• Schema listings
• DDL retrieval
• Connection tests
4. Timestamps: All operations are timestamped to the second
5. User Context: All operations are attributed to the "DONGHUA" user
This logging mechanism provides excellent traceability for all database operations performed through the MCP
interface, which is valuable for auditing and debugging purposes.
links:
