diff --git a/sqlcl-mcp-server-intro/1-introduction.md b/sqlcl-mcp-server-intro/1-introduction.md index e86815a08..115a90e69 100644 --- a/sqlcl-mcp-server-intro/1-introduction.md +++ b/sqlcl-mcp-server-intro/1-introduction.md @@ -13,10 +13,6 @@ In this workshop, you’ll learn how to connect an AI Agent (Cline) to the SQLcl - Register the SQLcl MCP Server with an AI Agent - Perform agent-driven Oracle AI Database tasks using sample prompts -[](include:test) - -
- ### What is MCP? The Model Context Protocol (MCP) is a proposed standard that lets AI Agents interact securely with your data and applications via an intermediary called an MCP Server. @@ -43,8 +39,6 @@ Users can request and perform database tasks from the Agent interface in plain l 5. Standard database security applies. 6. Results provided by the AI Agent; user can review/approve next steps. -
- ### Protocols & Capabilities You interact with MCP Servers through AI Agents; using natural language to invoke tools. The Agent might also use tools autonomously within "protocol" guidelines. @@ -61,7 +55,6 @@ You interact with MCP Servers through AI Agents; using natural language to invok ### The SQLcl MCP Server SQLcl is a powerful CLI for the Oracle AI Database. By extending it with an MCP Server, we can enable secure, natural-language database interaction through an AI Agent. In the next few labs you'll explore your database using an AI Agent along with the SQLcl MCP Server. -
#### Security Considerations when using the SQLcl MCP Server @@ -77,7 +70,7 @@ Some key principles to consider: - Audit actions in a database table - Use defense-in-depth: SQL Firewall, Data Vault, Resource Manager, Row Level Security -> ℹ **Note:** SQLcl MCP Server stores credentials securely in an Oracle Wallet—never exposed to the LLM/Agent. All database roles, privileges, and safeguards apply. +> **Note:** SQLcl MCP Server stores credentials securely in an Oracle Wallet—never exposed to the LLM/Agent. All database roles, privileges, and safeguards apply. ### General MCP Best Practices @@ -102,14 +95,10 @@ You may now [proceed to the next lab](#next). - [Oracle official MCP Server repository](https://github.com/oracle/mcp/tree/main) - [SQLcl MCP Server Docs](https://docs.oracle.com/en/database/oracle/sql-developer-command-line/25.2/sqcug/using-oracle-sqlcl-mcp-server.html) -**Acknowledgements:** -- Author: Chris Hoina, Senior Product Manager, Database Tools +## Acknowledgements + +- Author: Chris Hoina, Lead Principal Product Manager, Database Tools - Contributors: Jeff Smith, Linda Foindling -- Last updated: Chris Hoina, February 2026 +- Last updated: October 2026 - -## Acknowledgements - -* **Author** - TODO: Your Name, Your Title, Your Organization -* **Last Updated By/Date** - TODO: Your Name, Month Year diff --git a/sqlcl-mcp-server-intro/2-environment-set-up.md b/sqlcl-mcp-server-intro/2-environment-set-up.md index 336874d32..35940c11a 100644 --- a/sqlcl-mcp-server-intro/2-environment-set-up.md +++ b/sqlcl-mcp-server-intro/2-environment-set-up.md @@ -2,27 +2,44 @@ ## Introduction -Estimated Time: TODO - x minutes - +Estimated Time: 10 mins In this Lab, you will setup your working environment to use the SQLcl MCP Server along with the Cline for VS code extension. ### Objectives - + - Install: - SQL Developer for VS Code Extension - Cline for VS Code extension + + - Configure the SQLcl MCP server ### Prerequisites This lab assumes you have: - + * Access to an LLM Provider (via an API Key or similar authentication method) * Oracle Java 17 or 21 (recommended) installed * A personal computer or access to a workshop-provided workstation + * Reviewed the prerequisites of the Introduction lab + +**Break Glass in case of emergency** + +Copy and run this in your VM's VS Code terminal: + +```sh + +wget -P ~/Desktop/prompts \ + 'https://raw.githubusercontent.com/oracle-livelabs/developer/refs/heads/main/sqlcl-mcp-server-intro/files/create_a_react_app_prompt.md' \ + 'https://raw.githubusercontent.com/oracle-livelabs/developer/refs/heads/main/sqlcl-mcp-server-intro/files/create_data_and_views_prompt.md' \ + 'https://raw.githubusercontent.com/oracle-livelabs/developer/refs/heads/main/sqlcl-mcp-server-intro/files/create_an_html_dashboard_prompt.md' + +``` + + ## Task 1: Create a FreeSQL account [](include:freesql-create-freesql-account-with-vscode.md) @@ -64,6 +81,7 @@ This lab assumes you have: 6. You will use this FreeSQL user for the remainder of this LiveLab. Next, you'll create a database connection in SQL Developer for VS Code Extension. + ## Task 1: Download the Instance Wallet 1. In this Lab, you will use a Cloud Wallet to configure your connection in SQL Developer for VS Code. Return to your Autonomous AI database dashboard. @@ -84,7 +102,7 @@ This lab assumes you have: ![take-note-of-complete-path-of-wallet](./images/lab-2/take-note-of-complete-path-of-wallet.png " ") > ⚐ **Note:** You can drag and drop the .zip file into a terminal to quickly discover the complete path. - + ## Task 2: Create a new REST-enabled database user 1. In your Autonomous AI database console, click **Database Actions** then **View all database actions**. @@ -220,7 +238,7 @@ This lab assumes you have: -## Task 3:5: Installing the Cline for VS Code Extension +## Task 5: Installing the Cline for VS Code Extension 1. In the VS Code Extensions tab, search for the Cline extension. @@ -245,7 +263,9 @@ This lab assumes you have: 6. With your provider settings complete, you’re ready to configure the SQLcl MCP Server. -## Task 4:6: Configuring the SQLcl MCP server + + +## Task 6: Configuring the SQLcl MCP server 1. In VS Code, open the Command Palette and search for: Configure Cline SQLcl MCP. @@ -276,22 +296,23 @@ This lab assumes you have: ![sqlcl-now-in-installed-servers-tab](./images/lab-2/sqlcl-now-in-installed-servers-tab.png " ") 6. Click the SQLcl MCP server frame to expand. You’ll see a list of SQLcl MCP Server tools, parameters, and definitions. - - ![23-expanding-the-installed-mcp-server-to-reveal-tools](./images/lab-2/23-expanding-the-installed-mcp-server-to-reveal-tools.png " ") - -

- + | Tool | Purpose | Parameters | Parameter Definitions | |---|---|---|---| - | `list-connections` | Lists saved Oracle DB connection names. | | | - | `connect` | Interface to connect to, confirm, and list schemas. | | | - | `disconnect` | Disconnects current session and logs out. | | | - | `run-sqlcl` | Run SQLcl CLI commands in SQLcl, returns command results. | | | - | `run-sql` | Run SQL queries and return CSV-formatted results. | | | - | `schema-information`| Provides insights on the connected schema (metadata analysis). | | | - | `run-sql-async`| Executes SQL queries as background asynchronous tasks. | | | + | `connections_list` | Lists saved Oracle database connections. | | | + | `connect` | Connects to a saved Oracle database connection. | | | + | `disconnect` | Closes the current database connection. | | | + | `sqlcl_run` | Executes SQLcl-specific commands. | | | + | `sql_run` | Executes SQL, DML, DDL, or PL/SQL and returns CSV-formatted results. | | | + | `schema_information` | Describes objects in the connected schema. | | | + | `skills_sync` | Installs or refreshes Oracle-maintained skills in detected AI assistant skill directories. | | | + | `annotation_generate` | Previews or persists DESCRIPTION annotations for schema tables and columns. | | | + | `context_retrieve` | Retrieves relevant context from vector tables in the active database. | | | + | `request_status` | Retrieves the status and available result of an asynchronous tool request. | | | {: title="SQLcl MCP Server Tools"} + > Note: Parameters marked with an asterisk (`*`) are required. + 7. Your SQLcl MCP Server is configured. You may now [proceed to the next lab](#next). ## Troubleshooting @@ -321,8 +342,8 @@ Click the Configure tab to review your currently configured MCP Servers and to e ## Acknowledgements -* **Author:** Chris Hoina, Senior Product Manager, Database Tools +* **Author:** Chris Hoina, Lead Principal Product Manager, Database Tools * **Contributors:** Jeff Smith, Distinguished Product Manager, Database Tools -* **Last Updated:** Chris Hoina, February 2026 +* **Last Updated:** Chris Hoina, October 2026 diff --git a/sqlcl-mcp-server-intro/3-using-the-mcp-server.md b/sqlcl-mcp-server-intro/3-using-the-mcp-server.md index f2d0db411..f50e1c639 100644 --- a/sqlcl-mcp-server-intro/3-using-the-mcp-server.md +++ b/sqlcl-mcp-server-intro/3-using-the-mcp-server.md @@ -28,35 +28,19 @@ This lab assumes you have: * Configured an Oracle Database connection using the SQL Developer Extension for VS Code * Configured the SQLcl MCP Server for use with Cline for VS Code -

- -> ⚐ **Note:** If participating in a workshop, you may optionally use your the credentials provided to you. +> **Note:** If participating in a workshop, you may optionally use the credentials provided to you. ## Task 1: Testing your configuration -1. Is the MCP Server working? - - You will need to confirm that the SQLcl MCP Server is working *before* you can begin interacting with it. +1. Is the MCP Server working? You will need to confirm that the SQLcl MCP Server is working *before* you can begin interacting with it. 2. Locate the Cline extension. Ensure you see the Agent prompt. Notice the **Plan** and **Act** modes. You will toggle between these two modes depending on your intent or the prompts used. - ![cline-1](./images/lab-3/cline-1.png " " ) - -

- - > ⚠ **IMPORTANT:** For adhering to security best practices, ensure the "Auto-Approve" option is disabled. - -

- - 3. Enable **Plan** mode. Then, in the Task input area of Cline, enter the following prompt: @@ -70,11 +54,9 @@ This lab assumes you have: ![cline-2](./images/lab-3/cline-2.png " ") - > ⚐ **Note:** Note the tool name, followed by the arguments. In this case, Cline wants to "see" what database connections are available. + > **Note:** Note the tool name, followed by the arguments. In this case, Cline wants to "see" what database connections are available. -5. Select the **Approve** button to allow the Agent to continue its plan. - - The Agent will use your Oracle Database connection, and ask to connect to it, via the `connect` tool. +5. Select the **Approve** button to allow the Agent to continue its plan. The Agent will use your Oracle Database connection, and ask to connect to it, via the `connect` tool. 6. You will again be prompted to approve a request. The message will look something like this: @@ -101,11 +83,7 @@ This lab assumes you have: Now let me run a test query to verify everything is working properly. I'll start with a simple query to check the current database time: ``` - > ⚐ **Note:** LLM training data can vary widely among versions and vendors. Thus, an LLM may generate one of several different types of queries to satisfy our request to 'test' the connection and system. - - ⚠ **Warning:** It is very important that you review the SQL, or update your prompt to include the exact SQL you want the Agent to use. - -

+ > **Note:** LLM training data can vary widely among versions and vendors. Thus, an LLM may generate one of several different types of queries to satisfy our request to 'test' the connection and system. 9. Scroll through the "sql" attribute to review the SQL statement. @@ -128,7 +106,7 @@ This lab assumes you have: ![cline-4](./images/lab-3/cline-4.png " ") -> ⚐ **Note:** "Connected_User" will be the username you provided in the previous lab. + > **Note:** "Connected_User" will be the username you provided in the previous lab. ## Task 3: Exploring Tools @@ -137,7 +115,7 @@ This lab assumes you have: 2. Use a similar prompt so the AI Agent can use the correct Tool: ```txt - connect as the FREESQL_[your unique ID] user and use the sqlcl schema-information tool + connect as the [Your Username] user and use the sqlcl schema-information tool ``` ![prep-command-for-schema-information-tool](./images/lab-2/prep-command-for-schema-information-tool.png " ") @@ -184,8 +162,8 @@ This lab assumes you have: ## Acknowledgements -* **Author** -* **Contributors** -* **Last Updated By/Date** +* **Author:** Chris Hoina, Lead Principal Product Manager, Database Tools +* **Contributors:** Jeff Smith, Distinguished Product Manager, Database Tools +* **Last Updated:** Chris Hoina, October 2026 diff --git a/sqlcl-mcp-server-intro/4-build-database-objects.md b/sqlcl-mcp-server-intro/4-build-database-objects.md index 9a8d7321a..371a25f08 100644 --- a/sqlcl-mcp-server-intro/4-build-database-objects.md +++ b/sqlcl-mcp-server-intro/4-build-database-objects.md @@ -6,7 +6,7 @@ In this lab you will use the SQLcl MCP server to create new database tables and
-> ⚐ **Note:** A sample prompt has been provided for you. This Lab, screenshots, and expected output are based on the instructions provided in the sample prompt. +> **Note:** A sample prompt has been provided for you. This Lab, screenshots, and expected output are based on the instructions provided in the sample prompt.
@@ -33,9 +33,9 @@ This lab assumes you have: 1. A sample prompt has been provided for you (see below). This prompt can be used as-is with your Agent while in "Plan" mode. Alternatively you may use it as a reference, while creating your own scenario. -[Download prompt](./files/create_data_and_views_prompt.md?download=1) + [Download prompt](./files/create_data_and_views_prompt.md?download=1) - > **Note:** This Lab is designed to be open-ended, accordingly, your individual results will vary. Feel free to "go off-script"! + > **Note:** This Lab is designed to be open-ended, accordingly, your individual results will vary. Feel free to "go off-script"! 2. Review the provided prompt in your IDE or browser. You will notice a single heading and several sub-headings. Each sub-heading will serve as a phase or step for this scenario: @@ -164,8 +164,8 @@ This lab assumes you have: ## Acknowledgements -* **Author** -* **Contributors** -* **Last Updated By/Date** +* **Author:** Chris Hoina, Lead Principal Product Manager, Database Tools +* **Contributors:** Jeff Smith, Distinguished Product Manager, Database Tools +* **Last Updated:** Chris Hoina, October 2026 diff --git a/sqlcl-mcp-server-intro/5-build-a-react-app.md b/sqlcl-mcp-server-intro/5-build-a-react-app.md index adc029aa6..45084be61 100644 --- a/sqlcl-mcp-server-intro/5-build-a-react-app.md +++ b/sqlcl-mcp-server-intro/5-build-a-react-app.md @@ -30,19 +30,21 @@ This lab assumes you have: * Configured the SQLcl MCP Server for use with Cline for VS Code * This lab may require NPM, Node.js, and other web development libraries -

+> **Note:** In this lab you must allow your AI Agent to create a new project folder, scaffold a sample React application, and if required, install project dependencies (e.g., npm, Node, Express, React, etc. ). -> ⚐ **Note:** In this lab you must allow your AI Agent to create a new project folder, scaffold a sample React application, and if required, install project dependencies (e.g., npm, Node, Express, React, etc. ). +## Task 1: Review the prompt -

+ -## Task 1: Review the prompt +1. This environment has strict networking in place. In order to provide an AI agent with sufficient resources for this scenario, download the following [resources](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/developer-library/react-style-dashboard.zip). When prompting your agent, include these files, in addition to the provided prompt (below). + + 1. A sample prompt has been provided for you. You may review it here, open the `.md` file in a new tab, or download the file locally. -[Download prompt](./files/create_a_react_app_prompt.md?download=1) + [Download prompt](./files/create_a_react_app_prompt.md?download=1) -> **Note:** This Lab is designed to be open-ended, accordingly, your individual results will vary. Feel free to improvise! + > **Note:** This Lab is designed to be open-ended, accordingly, your individual results will vary. Feel free to improvise! 2. After reviewing the prompt, you may wish to save it locally. But, before you begin, review the various sections of the prompt: @@ -131,8 +133,8 @@ This lab assumes you have: ## Acknowledgements -* **Author** -* **Contributors** -* **Last Updated By/Date** +* **Author:** Chris Hoina, Lead Principal Product Manager, Database Tools +* **Contributors:** Jeff Smith, Distinguished Product Manager, Database Tools +* **Last Updated:** Chris Hoina, October 2026 diff --git a/sqlcl-mcp-server-intro/6-build-a-html-dashboard.md b/sqlcl-mcp-server-intro/6-build-a-html-dashboard.md index 3d85158c4..5d4951939 100644 --- a/sqlcl-mcp-server-intro/6-build-a-html-dashboard.md +++ b/sqlcl-mcp-server-intro/6-build-a-html-dashboard.md @@ -32,17 +32,19 @@ This lab assumes you have:

-> ⚐ **Note:** In this lab you must allow your AI Agent to create a new project folder, scaffold an HTML page, and if required, install dependencies (e.g., npm, Node, Express, etc.). +> **Note:** In this lab you must allow your AI Agent to create a new project folder, scaffold an HTML page, and if required, install dependencies (e.g., npm, Node, Express, etc.).

## Task 1: Review the sample prompt - + +1. This environment has strict networking in place. In order to provide an AI agent with sufficient resources for this scenario, download the following [resources](https://c4u04.objectstorage.us-ashburn-1.oci.customer-oci.com/p/EcTjWk2IuZPZeNnD_fYMcgUhdNDIDA6rt9gaFj_WZMiL7VvxPBNMY60837hu5hga/n/c4u04/b/livelabsfiles/o/developer-library/html-style-dashboard.zip). When prompting your agent, include these files, in addition to the provided prompt (below). + 1. A sample prompt has been provided for you. It can be used as-is in **Plan** mode with your Agent. Or, can use the prompt as a reference while you create your own dashboard. -[Download prompt](./files/create_a_react_app_prompt.md?download=1) + [Download prompt](./files/create_a_react_app_prompt.md?download=1) -> **Note:** This Lab is designed to be open-ended, accordingly, your individual results will vary. Feel free to "go off-script"! + > **Note:** This Lab is designed to be open-ended, accordingly, your individual results will vary. Feel free to "go off-script"! 2. Whether you use the prompt as-is or use it as a reference; you decide. Make sure to begin your workflow in **Plan** mode in order to have better control and oversight over the entire process. @@ -104,8 +106,8 @@ This lab assumes you have: ## Acknowledgements -* **Author** -* **Contributors** -* **Last Updated By/Date** +* **Author:** Chris Hoina, Lead Principal Product Manager, Database Tools +* **Contributors:** Jeff Smith, Distinguished Product Manager, Database Tools +* **Last Updated:** Chris Hoina, October 2026 diff --git a/sqlcl-mcp-server-intro/workshops/green-btn/index.html b/sqlcl-mcp-server-intro/workshops/sandbox/index.html similarity index 100% rename from sqlcl-mcp-server-intro/workshops/green-btn/index.html rename to sqlcl-mcp-server-intro/workshops/sandbox/index.html diff --git a/sqlcl-mcp-server-intro/workshops/green-btn/manifest.json b/sqlcl-mcp-server-intro/workshops/sandbox/manifest.json similarity index 95% rename from sqlcl-mcp-server-intro/workshops/green-btn/manifest.json rename to sqlcl-mcp-server-intro/workshops/sandbox/manifest.json index dc3802895..de716c641 100644 --- a/sqlcl-mcp-server-intro/workshops/green-btn/manifest.json +++ b/sqlcl-mcp-server-intro/workshops/sandbox/manifest.json @@ -12,6 +12,7 @@ }, { "title": "Environment set-up", + "type": "sandbox", "description": "Installing and configuring necessary dependencies and pre-requisites.", "filename":"../../2-environment-set-up.md" }, @@ -27,11 +28,13 @@ }, { "title": "Build a React app", + "type": "sandbox", "description": "Building a starter React-based application.", "filename":"../../5-build-a-react-app.md" }, { "title": "Build an HTML dashbaord", + "type": "sandbox", "description": "Building a starter HTML-dashboard.", "filename": "../../6-build-a-html-dashboard.md" },