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
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 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:
ARGUMENTS { |
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”, } |
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 { } |
Task 2: Ask for menu items
Task Breakdown
LLM Breaks Query down into subtasks
| Ask the database what menu items I have
|
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:
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.
- Check out our recent MySQL AI announcement
- Get a trial download of MySQL AI from Oracle E-Delivery today
- Get started with a free MySQL HeatWave instance today



