MySQL HeatWave is the only fully managed MySQL database service that combines transactions, analytics, machine learning, and GenAI services, without ETL duplication. Also included is MySQL HeatWave Lakehouse, which allows users to query data in object storage, MySQL databases, or a combination of both. Users can deploy MySQL HeatWave–powered apps on a choice of public clouds: Oracle Cloud Infrastructure (OCI), Amazon Web Services (AWS), and Microsoft Azure.

Introduction

This blog is focused on Model Context Protocol (MCP).  MCP is an open standard enabling seamless integration between applications powered by large language models (LLMs) and external data sources and/or tools. The MySQL HeatWave MCP Server provides a collection of specialized tools that help you leverage the full capabilities of both MySQL HeatWave and MySQL AI.

MCP Server for MySQL HeatWave

MySQL HeatWave enables users to conveniently leverage MySQL HeatWave’s and/or MySQL AI’s powerful capabilities in their applications. The diagram below shows the various tools supported by the MySQL HeatWave MCP server.

To set this server, please follow the instructions listed in the readme of the MCP server Github repository

tools supported by the MySQL HeatWave MCP server
Tools supported by the MySQL HeatWave MCP server

The MySQL HeatWave MCP server provides the following tools. Users can augment these for their use cases, by defining additional ones, as shown below:

Category

Tool

Description

 

Database Connection Management

Load connection configs from JSON/env vars

Import database configs from JSON files or environment variables

 

List all configured database connections

Display all available/pre-configured database connections

 

Validate connectivity and resolve provider mode

Test database connections and identify DB provider mode

 

Database Operations

Execute SQL queries

Run SQL statements against the connected database

 

GenAI Operations

Text generation with HeatWave GenAI

Use GenAI to generate or augment text

 

Create/populate vector columns for embeddings

Generate and save vector representations in DB columns

 

Retrieval-augmented generation from vector stores

Use vector store for improved GenAI results

 

Vector Store Ingestion

Load documents from Object Storage into vector store

Ingest files/objects from Object Storage to populate vector DB

 

OCI Object Store

List all compartments

Display all available OCI compartments

 

Get compartment by name

Find a compartment by its name

 

List buckets in a compartment

Show storage buckets within a selected compartment

 

List objects in a bucket

Display items stored in a specific storage bucket

 

All capabilities above excluding OCI Object Store are supported for both MySQL HeatWave and MySQL AI connections; furthermore, the MCP server enables users to specify either homogenous (all MySQL AI or MySQL HeatWave) database connections or heterogenous (some pointing to MySQL AI servers and some pointing to MySQL HeatWave servers) database connections ensuring that the MCP server is useable in any AI enabled MySQL setup. For more details and the most up to date list of capabilities, check out the readme on our public repository here.

Some powerful capabilities to highlight are Vector Store Ingestion along with OCI Object Store. This enables users to load and vectorize data from pdfs, docx, html, pptx, and txt directly into vector store. This capability is showcased in the HeatWave demo below.

In the following sections, we provide two examples of how the MCP server can be used to interact with the MySQL HeatWave database. Note that the user can write additional tools to tailor it for their specific use case.

Task 1: Ingest documents into vector store and ask simple questions

This section paraphrases a real application of the MySQL HeatWave MCP Server where a Cline client used the MCP server to load user data from object store into vector store with just two prompts from a non-expert user.

  • Black box shows the natural language instructions issued by the user

Grey boxes show the instructions/steps generated by the client for the server/tools

Can you help me load my menu item into the database? I think the PDF was called something like IRIS lunch menu and was in something called ILA compartment.

Task Breakdown

The client (via the orchestrating LLM) Breaks Query down into subtasks and then executes these subtasks. For brevity, we are only showing snippets of how the client has reasoned

  • The user wants to load menu items into a database from a PDF called something like “IRIS Lunch menu” in a compartment called “ILA”.
  • The file seems to be in OCI Object Storage under the ILA compartment, not on the local disk.
  • The goal is: (a) locate the file in OCI storage, (b) load it as a vector store or parse and import items, most likely via the mysql-mcp-server capabilities.
  • I’ll need the bucket and file name in the ILA compartment. Steps: (a) List all compartments, (b) List all buckets in the “ILA” compartment, (c) List objects in the most likely bucket, (d) confirm the exact name of the PDF, (e) load the PDF using the correct server tool.
  • Formulate a todo checklist reflecting this process. Begin by listing all compartments and searching for ILA

The client then executes each step with the tools provided by the HeatWave MCP server, provides the results, and moves to the next step

List all compartments (Step 4a)

Cline wants to use a tool on the mysql-mcp-server MCP server:

list_all_compartments

[MCP Tool] List all compartments in the tenancy. Args: None Returns: str: Stringified per-compartment access report: { “<compartment_name>”: { “compartment_id”: “<ocid>”, “object_storage”: true|false, “databases”: true|false, “errors”: [ “<error strings>” ] }, … } …..

List all buckets in the “ILA” compartment (4b)

Cline wants to use a tool on the mysql-mcp-server MCP server:

object_storage_list_buckets


[MCP Tool] List all accessible Object Storage buckets in a compartment. Args: compartment_name (str, optional): Case-insensitive compartment name to resolve to an OCID. compartment_id (str, optional): Compartment OCID. If provided, takes precedence over name resolution. Returns: str: Stringified list of oci.object_storage.models. BucketSummary objects on success. …..

ARGUMENTS

{
“compartment_name”: “ILA”
}

 

List all objects in the bucket (4c)

The clients get the names of all the buckets in the ILA compartment from the above query. It initially requested the objects in the wrong bucket, back tracked (not shown here), and then requested the objects in the right bucket (bucket-chicago-sp1)

Cline wants to use a tool on the mysql-mcp-server MCP server:

object_storage_list_objects

[MCP Tool] List objects stored in an OCI Object Storage bucket. Args: namespace (str): Object Storage namespace for the tenancy. bucket_name (str): Name of the bucket to list objects from. Returns: str: Stringified list of oci.object_storage.models.ObjectSummary ………..default profile).

ARGUMENTS
{

“namespace”: “mysqlpm”,
“bucket_name”: “bucket-chicago-sp1”

}

 

Loading into vector store (4d)

Client calls list_all_connections to identify the HeatWave connection, followed by   load_vector_store_oci to load the found menu data into vector store.

Cline wants to use a tool on the mysql-mcp-server MCP server:

list_all_connections

[MCP Tool] List configured connection keys, validate connectivity, and report mode. Args: None Returns: str: JSON-encoded object: { “valid keys”: [{“key”: string, “mode”: “MYSQL_AI” | “OCI”}], “invalid keys”: [{“key”: string, “error”: string, “hint”: string}] } Notes: – …….

 

Cline wants to use a tool on the mysql-mcp-server MCP server:

load_vector_store_oci

[MCP Tool] Load documents from OCI Object Storage into a Heatwave vector store. Purpose: Load documents from object storage into a vector store for similarity search and RAG. The document_prefix can be a file name, a directory/prefix, or a partial prefix. Examples (assuming these objects exist in the bucket): heatwave-en-ml-9.2.0.pdf sample_files/document1.pdf sample_files/document2.pdf sample_files/documents_345.docx Valid document_prefix values: ‘heatwave-en-ml’ ……

ARGUMENTS

{

“connection_id”: “remote_via_bastion”,

“namespace”: “mysqlpm”,

“bucket_name”: “bucket-chicago-sp1”,

“document_prefix”: “restaurant_menus/PLUEP1EQiqfnaWZyVMYK_7.23.25 IRIS Lunch Menu Update.pdf”

}

 

Cline wants to use a tool on the mysql-mcp-server MCP server:

execute_sql_tool_by_connection_id

Execute a SQL script on the specified database connection. Args: connection_id (str): The key identifying the database connection to use. sql_script (str): The SQL statement to execute. Can be a query or a DML/DDL statement. params (list, optional): List of parameters to use for parameterized SQL scripts. If None, executes with no bind variables. Returns: ….. [42])

ARGUMENTS

{
“connection_id”: “remote_via_bastion”,

“sql_script”: “SELECT mysql_tasks.task_status_brief (\”6235bc70-a54a-11f0-84f9-02001704f393\”);”
}

 

Task 2: Ask for menu items

Task Breakdown

LLM Breaks Query down into subtasks

Ask the database what menu items I have

  1. The user wants to query the vector store/database to extract/see the menu items from the uploaded “IRIS Lunch Menu” PDF.
  2. The optimal approach is to use the AI vector store RAG query capability, which will retrieve the recognized menu items, since the file was processed as an OCR’d PDF
  3. Use the ask_ml_rag_vector_store tool to ask: “What menu items do I have?” (which will return a list or summary from the ingested menu document).
  4. Use the valid connection key: “remote_via_bastion”.

Query the Vector Store 

ask_ml_rag_vector_store

[MCP Tool] Retrieve segments from the default vector store (skip_generate=true). Args: connection_id (str): MySQL connection key. question (str): Natural language query. context_size (int): between (inclusive) 10 and 100, the context size for RAG. Try increasing if RAG call does not provide sufficient relevant documents. Returns: str: Scalar result from SELECT @response (often JSON). On error, a JSON-encoded object. Implementation details: – Equivalent to ask_ml_rag(connection_id, question). MCP usage example: – name: ask_ml_rag_vector_store arguments: {“connection_id”: “example_local_server”, “question”: “Find information about refunds.”}

ARGUMENTS

{

“connection_id”: “remote_via_bastion”,

“question”: “What menu items do I have?”, “context_size”: 40

}

 

LLM Response

Here is the final response:

The menu items currently in your database from the “IRIS Lunch Menu” include:

  • Iris Tzatziki (v): fennel pollen, sorrel (16)
  • Hummus (v): sumac, sesame (14)
  • Roasted Eggplant (v): pine nut, golden raisin (12)
  • Whipped Feta (v): (13)
  • Village Salad (v): hot house tomato, cucumber, red onion, citrus marinated feta, olive (24/34)
  • Add: falafel (10), chicken (10), shrimp (12), lamb (14)
  • Little Ram Oysters*: pink peppercorn mignonette (18/33)
  • Grilled Lagana Bread: taramasalata, pickled ramps, soft herbs (14)
  • Dolmas (v): lemon agrumato, valencia orange (8)
  • Hand-Cut Fries: lemon, oregano (14)
  • Fried Squid: dashi lime aioli (19)
  • Orzotto: (12)
  • Swiss chard, kale, elephant garlic
  • Grilled Octopus: potato-labne puree, cured lemon, paprika aioli (32)
  • Quail Kebab: pepper crusted, sage butter, braised wild greens (32)

These were extracted using vector search from the uploaded PDF menu. Let me know if you want specific menu item details, prices, or further queries.

 

Summary

We have demonstrated how even a non-expert can use a chat agent to accomplish complex tasks in HeatWave with just a few simple prompts using our MySQL HeatWave MCP Server.

Learn More

Check out our MySQL HeatWave and MySQL AI documentation to learn more about all of the exciting GenAI and Machine Learning capabilities.