Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

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

Written by
Improved by
Updated at October 30, 2025

In this tutorial, you will learn how to work with a YDB database using LLMs. This will allow you to manage your database using a human language to fix errors, optimize the DB, and analyze data.

As an example, we will take a cloud-based or local YDB instance that you will connect to via a 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

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 sends 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 started

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

Note

You can use this tutorial with other IDEs or models. Here, we selected Cursor as a ready-made solution to skip the setup step.

Preparing 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 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. In the project folder, run the docker compose build command in the terminal to build the project’s containers.

Create a database in Managed Service for YDB

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):

  1. In the management console, select a folder to create a database in.

  2. Select Managed Service for YDB.

  3. Click Create a database.

  4. Specify a Name for the database. Follow these naming requirements:

    • It must be from 2 to 63 characters long.
    • It can only contain lowercase Latin letters, numbers, and hyphens.
    • It must start with a letter and cannot end with a hyphen.

  5. Under Database type, select Serverless.

  6. Click Create a database.

  7. Wait until the database starts. While being created, your database will have the Provisioning status. Once it is ready for use, its status will change to Running.

  8. Select the database you created.

  9. Under Connection, find the Endpoint and Path to database fields and save their values. You will need them to configure a connection to the database.

You can create a YDB database by calling the yc CLI utility.

yc ydb database create test --serverless

Create an authorized key

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

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.

  1. In the management console, select the folder the service account belongs to.

  2. In the list of services, select Identity and Access Management.

  3. In the left-hand panel, select Service accounts.

  4. In the list that opens, select the service account you created.

  5. Click Create new key in the top panel.

  6. Select Create authorized key.

  7. Select the encryption algorithm.

  8. Enter a description for the authorized key so you can easily find it in the management console.

  9. Save the key in the authorized_key.json file in the project folder:

    {
  "service_account_id": "<sa-function_service_account_ID>",
  "key_algorithm": "RSA_2048",
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
}

In the project folder, run this command in the terminal:

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

For more information about the yc iam key create command, see this CLI reference.

If successful, the key will be saved to the authorized_key.json file.

Warning

The authorized_key.json file contains the key’s secret part that you can use to access databases in your folder. Keep it secure. In the demo project, it is already added to .gitignore.

Specify settings database connection settings in ydb.env

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

  1. Copy the ydb-template.env file to ydb.env.
  2. Fill in the parameters for the connection 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 info.

Test the application

In the Cursor IDE terminal, from the project folder, run commands to test the application. After each step, make sure the commands complete 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 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 and try running your own server, 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 model

If you are using a trial account, skip this section as you will be unable 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 the choice of model: 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 YDB MCP

Populating 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 command for the LLM:

Create 15 test notes and write them to YDB. The note dates must be within the `2001-01-01` to `2001-12-31` range. 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 test 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 first try. In which case the model rewrites the query based on the error text and tries again. The number of attempts depends on the model and the quality of the query. You do not need to intervene: the model will fix the errors all by itself 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 server

You can use LLMs not only to write code or populate a database, but also to fix errors. This way, you can troubleshoot errors in data, a 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 schema

To simulate an error, rename the table:

  1. Log in to the management console.
  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>

Note

The text copied from the Cursor terminal will not appear in the chat; the error will be displayed as a link in the window header.

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 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 run this command:

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

Collecting analytics on the connected database

AnnLLM with ydb-mcp can be used not only for data modification, but also for 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 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 an ability to store note attachments. Tell me how to achieve this with our current database schema.

Results

Currently, LLMs can solve a wide range of tasks, but they cannot interact with the outside world. MCP provides this connection. When using the YDB MCP server, an LLM gains access to the database and is able 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 the database schemas or data.

Warning

Use LLMs with caution and do not connect to critical databases. Via an MCP server, an LLM gains all permissions assigned to the service account. We recommend creating a database copy to work with. For example, during its operation, the model may send a request to delete all data or run a very large query that would interfere with the main load.

Deleting resources

To free up resources, follow this guide to delete the YDB test database.

Previous
Monitoring DB status
Next
All tutorials