How to use LLMs to work with Yandex Managed Service for YDB via an MCP server: Cursor IDE example

In this tutorial, you will learn how to work with a YDB database using large language models (LLMs). This way, you will be able to fix errors, optimize your database, and analyze data using a human language.

As an example, we will take a cloud-based or local YDB instance that you will connect to via an MCP server running on your machine. We will use the Cursor IDE to access the MCP server and integrate an LLM for natural language processing. You can easily write and send queries in your native language, and the model, along with the MCP server, will convert them into accurate SQL queries for YDB and assist with error correction and optimizations.

• Terms
• Getting started
• Setting up the environment
• Working with the YDB MCP
• Prompts for experimentation
• Results
• Deleting resources

TermsTerms

Cursor: IDE with native LLM integration.

LLM: Large language model, e.g, YandexGPT. It can generate text, but cannot connect to external systems, such as databases, on its own. To enable access to such systems, you need an MCP client, e.g., Cursor, that connects to an MCP server which, in turn, interacts with the database.

MCP (Model Context Protocol): Open protocol an MCP client uses to connect to an MCP server and enable LLM access to external systems. For more information on MCP, see this page.

MCP client: Software connecting an LLM with an MCP server and integrating MCP server tools in a dialog for the LLM to use. In this tutorial, we are using the Cursor IDE as an MCP client.

MCP server: Standalone application that connects to an external system (in our case, YDB) and enables access to specific tools. The MCP server itself does not have any complex logic; it only connects the LLM to external systems. The LLM decides how and which tools to use based on the prompt you provide. Different LLMs may have their distinct approaches to a task: one would generate a final YQL query right away, while another would iterate on versions and fix errors on the fly.

ydb-mcp: MCP server implemented by the YDB team.

For different operations, ydb-mcp offers different tools, e.g., ydb_status tests the connection, and ydb_query runs queries. These tools are similar to API functions: you feed them parameters and get a result.

It is the same with developers: with the same API, each one will have different code. In the case of LLMs, the result depends not only on the MCP server but also the model’s capabilities.

Getting startedGetting started

Paid resourcesPaid resources

1. Cursor IDE account (you can use the trial version).
2. Fee for YDB operations and data storage (see Yandex Managed Service for YDB pricing).

Setting up the environmentSetting up the environment

1. Install the Cursor IDE.
2. Install Docker Desktop or Docker Engine (CE) together with the Docker Compose plugin, which you will need to run the project.

Clone and open the projectClone and open the project

1. Clone the project from the ydb-mcp-demo-notes repository. If Git is not installed, download and unpack main.zip.
2. Open the project folder in the Cursor IDE: in the File menu, select Open Folder and specify the project folder.
3. Open the terminal (View → Terminal or Ctrl/Cmd + Backtick).
4. From the project folder, run the docker compose build command in the terminal to build the project’s containers.

Create a Managed Service for YDB databaseCreate a Managed Service for YDB database

Create a database in serverless mode. This is a convenient option for a cloud environment. On a local machine, run a docker container (Docker x86_64 tab):

yc ydb database create test --serverless

Create an authorized keyCreate an authorized key

If working with a local Docker container, skip this step.

Create a service account and assign it the ydb.editor role for your folder. In our example, we will use the LLM to update the database; if you do not need to do this, a more secure option is to assign the ydb.viewer role.

yc iam key create --service-account-name sa-function -o authorized_key.json

Specify the database connection settings in ydb.envSpecify the database connection settings in ydb.env

If working with a local Docker container, skip this step.

1. Copy the ydb-template.env file to ydb.env.
2. Enter the parameters for connecting to the database you created earlier:
   • YDB_AUTH_MODE=service-account: The key name (authorized_key.json) is built into the example; you do not needed to specify it.
   • YDB_ENDPOINT and YDB_DATABASE: Get values from the database details.

Test the applicationTest the application

In the Cursor IDE terminal, from the project folder, run commands to test the application. After each step, make sure the commands run without errors:

docker compose run --rm notes-app init
docker compose run --rm notes-app add "Test" "This is my first note in YDB-notes"
docker compose run --rm notes-app list

Starting the MCP serverStarting the MCP server

The parameters for starting the MCP server are already set in the .cursor/mcp.json file in the demo project. If you want to learn how to run your own server and try it, see ydb-mcp tutorials.

1. Open the Cursor Settings menu (do not confuse it with VS Code Settings).
2. Navigate to MCP & Settings.
3. Toggle on the switch next to ydb. If it is already on, toggle it off, then on again, so that the MCP server restarts with new settings.
4. After it starts, next to the ydb MCP server, you will see a list of tools and an icon indicating the server is running.
5. Test the connection by opening the AI panel on the right (Ctrl/Cmd + L) and entering this in the chat: Check connection to YDB. The output should inform you that the connection works correctly.

Select a modelSelect a model

If you are using a trial account, skip this step as you will not be able to select a model. All examples from this tutorial will also work for the auto mode, but the model will be able to perform more operations, and the result will be less predictable.

In the chat window under the input field, find the Auto sign, click it, and disable auto selection in the window that opens.

You will see a list of available models: select a model from the claude- family, e.g., claude-4-sonnet or a newer version.

The LLM you select does not affect the MCP server performance. However, the steps and the result are directly affected by your choice: it is the model that decides which operations to perform via MCP. Examples in this tutorial were tested using claude-4-sonnet in Auto mode, but you can try other models as well.

Working with the YDB MCPWorking with the YDB MCP

Populating a table with test data via the MCP serverPopulating a table with test data via the MCP server

Sometimes you have to populate an empty database with test data. You can delegate this task to the LLM: it will generate data and add it to the database via the MCP server.

Example of a command for the LLM:

Create 15 test notes and write them to YDB. The note dates must be from `2001-01-01` to `2001-12-31`. The notes should be in English and Russian.

Here is how it works:

1. Cursor provides the description of the MCP server and its tools to the model.
2. The LLM uses the ydb_status tool to check the database connection.
3. The LLM uses ydb_query to send queries to add rows. This YQL query must be accurate: sometimes it is not accepted on the first try. In this case, the model rewrites the query based on the error text and makes another attempt. The number of attempts depends on the model and the quality of the query. You do not need to intervene: the model will fix any errors on its own and, finally, add the required number of notes.

To check the results, run the docker compose run --rm notes-app list command. You will see the notes the LLM has created. You can use this method to populate more complex databases as well.

Fixing errors using the MCP serverFixing errors using the MCP server

You can use LLMs not only to write code or populate a database, but also to fix errors in your data, your database schema, or application source code. To demonstrate how it works, let’s create an error on purpose by renaming a table in the database.

Without MCP, the LLM would have only the source code and error text. In this case, it would suggest rerunning the init command or creating a table via a query. With MCP, there are more options: the model can request the database schema and perform any operation, e.g., undo table renaming or copy the table.

Fixing a database schemaFixing a database schema

To simulate an error, rename the table:

1. In the management console, select the folder the database resides in.
2. Go to Managed Service for YDB and open your database.
3. Click Navigation, then New SQL query, and run this query to rename the table:

ALTER TABLE notes RENAME TO notes2

After that, run docker compose run --rm notes-app list and make sure you get the error.

Start a new Cursor chat and describe the issue:

There is something I did, and the application stopped displaying notes. Check the database and fix it to make it work again. Do not modify the code. Error: <paste the error text here>

The LLM will check the database’s current state via MCP, find the renamed table, and try to fix that. It may rename the table back, create a new table and transfer the data, or perform a migration. Each time you run the model, it may select different options.

Adjusting the source code to the schema updatesAdjusting the source code to the schema updates

Delete the temporary notes2 table if left after the previous step so it does not affect any further tests:

DROP TABLE IF EXISTS notes2

Now, rename the main table again:

ALTER TABLE notes RENAME TO notes_new

Open a new chat and enter this command:

The table name in YDB has changed. Fix the app’s source code to use the new name and check that all commands from the instructions still run correctly.

Collecting analytics on the connected databaseCollecting analytics on the connected database

Not only an LLM with ydb-mcp can modify data, but also run analytical queries, e.g., to quickly get a summary or calculate statistics directly in the database.

• Calculate the distribution of the note creation time by hour of day (number of notes for each hour).
• Calculate the average and median note length values. Use YQL on the server side to run the calculations.

Prompts for experimentationPrompts for experimentation

Use cases for ydb-mcp go far beyond the scope this article covers. LLM access to a real database schema and data provides many integration opportunities. Below, you will find examples of other tasks you can experiment with.

• My query, <...>, works slowly, find ways to make it run faster.
• Create wrapper functions to access records in the notes table.
• Create CRUD functions for tables in my database.
• Implement the option to store note attachments. Tell me how to do it with our current database schema.

ResultsResults

Currently, LLMs can solve a wide range of tasks, but they cannot interact with external systems. MCP provides this connection. When using the YDB MCP server, an LLM gains access to the database to manage it. Now, you are not limited to the source code database schema, but can also work with its actual state. For example, the LLM can change your database schema or data.

Deleting resourcesDeleting resources

To free up resources, delete the YDB test database as described in this guide.