From 2e8ae24c33c6694969971370af0cf82ac68bc81e Mon Sep 17 00:00:00 2001 From: Antoine Champion Date: Tue, 13 May 2025 20:30:53 +0200 Subject: [PATCH 1/3] feat(tutorial): connect generative apis to sql with mcp --- .../connect-generative-apis-sql/index.mdx | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 tutorials/connect-generative-apis-sql/index.mdx diff --git a/tutorials/connect-generative-apis-sql/index.mdx b/tutorials/connect-generative-apis-sql/index.mdx new file mode 100644 index 0000000000..9021be9077 --- /dev/null +++ b/tutorials/connect-generative-apis-sql/index.mdx @@ -0,0 +1,192 @@ + +--- +meta: + title: Connect Generative APIs to Serverless SQL with the Model Context Protocol + description: Create an intelligent agent that can analyze your Serverless SQL data using natural language queries through Model Context Protocol. +content: + h1: Connect Generative APIs to Serverless SQL with the Model Context Protocol + paragraph: Create an intelligent agent that can analyze your Serverless SQL data using natural language queries through Model Context Protocol. +tags: AI MCP SQL agent python database +categories: + - generative-apis + - serverless-sql +dates: + validation: 2025-05-13 + posted: 2025-05-13 +--- + +[Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open, standardized communication protocol that enables Large Language Models to interact with external tools and services through a defined interface. + +This tutorial demonstrates how to build a data analysis agent that connects Scaleway's Generative APIs with Serverless SQL using MCP. You'll learn how to create an AI agent that can: +- Understand your database schema automatically +- Convert natural language questions into SQL queries +- Execute queries and present results in human-friendly format + + + +- A Scaleway account logged into the [console](https://console.scaleway.com) +- Python 3.9 or higher +- An API key from Scaleway [Identity and Access Management](/iam/) +- Access to Scaleway [Generative APIs](/generative-apis/quickstart/) and [Serverless SQL](/serverless-sql/quickstart/) + +## Introduction + +The solution consists of three main components: + +1. **Generative APIs**: Provides the AI model that processes natural language queries +2. **Serverless SQL**: Stores and manages the data +3. **Local AI agent**: Coordinates between the AI model and database + + + The agent runs on a local machine in this tutorial but could also be embedded as a remote application. + + +## Configuring Scaleway services + +### Set up Generative APIs + +1. Go to the Scaleway console and navigate to **Generative APIs** +2. Select a model (Mistral Small is used for this tutorial) +3. Click **View Code* and note down the *base URL* and *model name* + +### Configure Serverless SQL + +1. Go to **Databases** > **Serverless SQL** +2. Create a new database with default settings +3. Click **Connect application** > **Connect with an existing IAM Secret Key** +4. Switch to the **Connection string** tab and copy the connection string + +### Seed the database + +Connect to your database and run the following SQL to create a test schema with some data: + +```sql +CREATE TABLE Sales ( + Product VARCHAR(50), + Buyer VARCHAR(50), + Timestamp TIMESTAMP +); + +INSERT INTO Sales (Product, Buyer, Timestamp) VALUES + ('Laptop', 'Alice', NOW() - INTERVAL '2 days'), + ('Tablet', 'Bob', NOW() - INTERVAL '3 days'), + ('Webcam', 'Ivan', NOW() - INTERVAL '30 minutes'), + ('Printer', 'Judy', NOW() - INTERVAL '12 hours'); +``` + +## Setting up the development environment + +The AI Agent is built in Python using the [fast-agent](https://github.com/evalstate/fast-agent) open-source framework which has native support for the MCP protocol. + +The [postgres-mcp](https://github.com/crystaldba/postgres-mcp) MCP server is used to communicate with Serverless SQL. + +1. Install a package manager. `uv` is the recommended package manager by `fast-agent`: + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + +2. Create and activate a virtual environment: + ```bash + uv venv + ``` + +3. Install required libraries: + ```bash + uv pip install fast-agent-mcp postgres-mcp + ``` + +These libraries work together to create a secure and efficient bridge between the AI model and your database. + +## Creating the AI Agent + +### Configure the agent + +Create a file called `fastagent.config.yaml`: + +```yaml +default_model: "generic." + +generic: + api_key: "" + base_url: "" + +mcp: + servers: + database: + command: "uv" + args: ["run", "postgres-mcp"] + env: + DATABASE_URI: "" +``` + +### Create the agent script + +Create a file called `agent.py` which will contain your agent logic. + +1. Import the necessary modules and initialize the agent: + ```python + import asyncio + from mcp_agent.core.fastagent import FastAgent + + fast = FastAgent("AI Agent") + ``` + +2. Create agents with different responsibilities: + ```python + @fast.agent( + "db_schema_reader", + instruction="""Get the details of the 'sales' table in the 'public' schema of the database, which contains the sales data. Only return the column names and types.""", + servers=["database"], + ) + @fast.agent( + "query_writer", + instruction="""Write a SQL query to fetch the sales data from the database (sales table) given the input constraint. Only return the SQL query, no other text.""" + ) + @fast.agent( + "query_executor", + instruction="""Execute the following SQL statement on the database and write the results in JSON format""", + servers=["database"], + ) + ``` + + + Each agent has a specific role. Some agents need direct database access through the MCP server (using the `servers=["database"]` parameter) while others don't + + +3. Create an orchestrator that coordinates the specialized agents: + ```python + @fast.orchestrator( + name="sales_analyst", + agents=["db_schema_reader","query_writer","query_executor"], + plan_type="iterative", + plan_iterations=4, + instruction="You are a sales analyst given an input criteria. Describe the corresponding sales data from the database in one sentence." + ) + ``` + The orchestrator: + - Determines which agents to use and in what order + - Sets an overall goal for the agent system + - Uses an iterative planning approach to refine the results + - Limits the number of iterations to prevent infinite loops + +4. Create an entrypoint running the data analysis query **Get sales from last day**: + ```python + async def main() -> None: + async with fast.run() as agent: + await agent.sales_analyst("Get sales from last day") + + if __name__ == "__main__": + asyncio.run(main()) + ``` + +5. Run the script with: + ```bash + python agent.py + ``` + +The `fast-agent` framework provides details of all operations and outputs its data analysis: + + The sales data from the last day includes two transactions: a webcam purchased by Ivan at 14:52 and a printer purchased by Judy at 03:22. + + +This tutorial demonstrated how to create an AI agent that can analyze your SQL database using natural language queries. By combining Scaleway **Generative APIs** with **Serverless SQL** through Model Context Protocol, you can create powerful tools that are accessible to non-technical users. From 5340d327d07d052999b83d0c08d40f97d6c17ab9 Mon Sep 17 00:00:00 2001 From: Antoine Champion Date: Mon, 19 May 2025 14:27:10 +0200 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Rowena Jones <36301604+RoRoJ@users.noreply.github.com> --- tutorials/connect-generative-apis-sql/index.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tutorials/connect-generative-apis-sql/index.mdx b/tutorials/connect-generative-apis-sql/index.mdx index 9021be9077..e9485bdecb 100644 --- a/tutorials/connect-generative-apis-sql/index.mdx +++ b/tutorials/connect-generative-apis-sql/index.mdx @@ -25,6 +25,7 @@ This tutorial demonstrates how to build a data analysis agent that connects Scal - A Scaleway account logged into the [console](https://console.scaleway.com) +- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing actions in the intended Organization - Python 3.9 or higher - An API key from Scaleway [Identity and Access Management](/iam/) - Access to Scaleway [Generative APIs](/generative-apis/quickstart/) and [Serverless SQL](/serverless-sql/quickstart/) @@ -52,13 +53,13 @@ The solution consists of three main components: ### Configure Serverless SQL 1. Go to **Databases** > **Serverless SQL** -2. Create a new database with default settings +2. [Create a new database](/serverless-sql-databases/how-to/create-a-database/) with default settings 3. Click **Connect application** > **Connect with an existing IAM Secret Key** 4. Switch to the **Connection string** tab and copy the connection string ### Seed the database -Connect to your database and run the following SQL to create a test schema with some data: +[Connect to your database](/serverless-sql-databases/how-to/connect-to-a-database/) and run the following SQL to create a test schema with some data: ```sql CREATE TABLE Sales ( From e842e2baccb8699dde0a0cc8e95bd669fa5a543a Mon Sep 17 00:00:00 2001 From: Antoine Champion Date: Sat, 31 May 2025 01:10:55 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Jessica <113192637+jcirinosclwy@users.noreply.github.com> --- tutorials/connect-generative-apis-sql/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/connect-generative-apis-sql/index.mdx b/tutorials/connect-generative-apis-sql/index.mdx index e9485bdecb..005156e4ec 100644 --- a/tutorials/connect-generative-apis-sql/index.mdx +++ b/tutorials/connect-generative-apis-sql/index.mdx @@ -20,7 +20,7 @@ dates: This tutorial demonstrates how to build a data analysis agent that connects Scaleway's Generative APIs with Serverless SQL using MCP. You'll learn how to create an AI agent that can: - Understand your database schema automatically - Convert natural language questions into SQL queries -- Execute queries and present results in human-friendly format +- Execute queries and present results in a human-friendly format