de en es ja ko ru zh

YDB MCP

Name: YDB MCP
Author: ydb-platform

Official

by ydb-platform

Overview Schema Source Related Servers Discussions Admin

Python

Remote

YDB MCP

License PyPI version

Model Context Protocol 服务器，适用于 YDB。它允许任何支持 MCP 的 LLM 与 YDB 数据库进行交互。此集成支持 AI 驱动的数据库操作，并允许与您的 YDB 实例进行自然语言交互。

使用方法

通过 uvx

uvx 是 uv run tool 的别名，允许您在不显式安装的情况下运行各种 Python 应用程序。以下是如何使用 uvx 配置 YDB MCP 的示例。

示例：使用匿名身份验证

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

通过 pipx

pipx 允许您在不显式安装的情况下从 PyPI 运行各种应用程序。但是，必须先安装它。以下是如何使用 pipx 配置 YDB MCP 的示例。

示例：使用匿名身份验证

{
  "mcpServers": {
    "ydb": {
      "command": "pipx",
      "args": [
        "run", "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

通过 pip

YDB MCP 可以使用 Python 的包安装程序 pip 进行安装。该包可在 PyPI 上获取，并包含所有必要的依赖项。

pip install ydb-mcp

要开始使用 YDB MCP，您需要配置 MCP 客户端以与 YDB 实例通信。以下是示例配置文件，您可以根据自己的设置进行自定义，然后放入 MCP 客户端的设置中。Python 解释器的路径可能也需要调整为安装了 ydb-mcp 包的正确虚拟环境。

示例：使用匿名身份验证

{
  "mcpServers": {
    "ydb": {
      "command": "python3",
      "args": [
        "-m", "ydb_mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

身份验证

无论使用哪种方法（uvx、pipx 或 pip），您都可以为您的 YDB 安装配置身份验证。为此，请传递特殊的命令行参数。

使用登录名/密码身份验证

要使用登录名/密码身份验证，请指定 --ydb-auth-mode、--ydb-login 和 --ydb-password 参数：

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "login-password",
        "--ydb-login", "<your-username>",
        "--ydb-password", "<your-password>"
      ]
    }
  }
}

使用访问令牌身份验证

要使用访问令牌身份验证，请指定 --ydb-auth-mode 和 --ydb-access-token 参数：

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "access-token",
        "--ydb-access-token", "qwerty123"
      ]
    }
  }
}

使用服务账户身份验证

要使用服务账户身份验证，请指定 --ydb-auth-mode 和 --ydb-sa-key-file 参数：

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "service-account",
        "--ydb-sa-key-file", "~/sa_key.json"
      ]
    }
  }
}

Related MCP server: GreptimeDB MCP Server

可用工具

YDB MCP 提供以下工具用于与 YDB 数据库交互：

ydb_query：对 YDB 数据库运行 SQL 查询
- 参数：
  - sql：要执行的 SQL 查询字符串
ydb_query_with_params：运行带有 JSON 参数的参数化 SQL 查询
- 参数：
  - sql：带有参数占位符的 SQL 查询字符串
  - params：包含参数值的 JSON 字符串
ydb_explain_query：解释 SQL 查询（返回执行计划）
- 参数：
  - sql：要解释的 SQL 查询字符串
ydb_explain_query_with_params：解释参数化 SQL 查询
- 参数：
  - sql：带有参数占位符的 SQL 查询字符串
  - params：包含参数值的 JSON 字符串
ydb_list_directory：列出 YDB 中的目录内容
- 参数：
  - path：要列出的 YDB 目录路径
ydb_describe_path：获取有关 YDB 路径（表、目录等）的详细信息
- 参数：
  - path：要描述的 YDB 路径
ydb_status：获取 YDB 连接的当前状态

构建自定义 MCP 服务器

YDBMCPServer 设计为可被继承。您可以在已建立的 YDB 连接之上添加自己的工具，并可选择禁用内置的通用工具，仅公开应用程序所需的查询。

为什么要构建自定义服务器？

安全性 — 将 LLM 限制为一组固定的只读查询，而不是公开任意 SQL 执行。
领域特定性 — 为模型提供符合您业务逻辑的工具，而不是原始数据库原语。
简洁性 — 更少的工具意味着模型更少的歧义。

可用方法

在您的子类中重写或调用这些方法：

方法	描述
`await self.execute(sql, params=None)`	运行 SQL 查询。返回 `list[dict]`，每个字典包含 `"columns"` 和 `"rows"`。
`await self.explain(sql, params=None)`	将查询执行计划作为 `dict` 返回。
`await self.list_directory(path)`	列出 YDB 目录。返回包含 `"path"` 和 `"items"` 的 `dict`。
`await self.describe_path(path)`	描述 YDB 路径（表结构、目录等）。返回一个 `dict`。

params 参数是一个普通的 dict。没有 $ 前缀的键会自动添加该前缀。要指定显式的 YDB 类型，请使用 (value, "TypeName") 元组 — 例如 {"id": (42, "Int64")}。

控制通用工具

使用 generic_tools 类属性来控制注册哪些内置工具：

值	效果
`set(YDBGenericTool)`	所有内置工具（默认）
`set()`	无内置工具 — 仅限您自己的工具
`{YDBGenericTool.QUERY, YDBGenericTool.STATUS}`	仅列出的工具

YDBGenericTool 是一个字符串枚举 — 可用值：QUERY、QUERY_WITH_PARAMS、EXPLAIN、EXPLAIN_WITH_PARAMS、STATUS、LIST_DIRECTORY、DESCRIBE_PATH。

示例

# my_server.py
from ydb_mcp import YDBMCPServer, YDBGenericTool, serialize_ydb_response


class OrdersServer(YDBMCPServer):
    """Minimal read-only MCP server for the orders service."""

    generic_tools = {YDBGenericTool.STATUS}  # keep status check for diagnostics

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        @self.tool()
        async def get_order(order_id: str) -> str:
            """Fetch a single order by ID."""
            rows = await self.execute(
                "SELECT * FROM orders WHERE id = $id",
                {"id": order_id},
            )
            return serialize_ydb_response(rows)

        @self.tool()
        async def list_recent_orders(limit: int = 10) -> str:
            """Return the most recent orders."""
            rows = await self.execute(
                "SELECT * FROM orders ORDER BY created_at DESC LIMIT $limit",
                {"limit": limit},
            )
            return serialize_ydb_response(rows)


if __name__ == "__main__":
    OrdersServer(
        endpoint="grpc://localhost:2136",
        database="/local",
    ).run()

直接运行它：

python my_server.py

或者在您的客户端配置中将其连接为 MCP 服务器：

{
  "mcpServers": {
    "orders": {
      "command": "python",
      "args": ["my_server.py"]
    }
  }
}

开发

该项目使用 Make 作为其主要开发工具，为常见的开发任务提供了一致的接口。

可用 Make 命令

该项目包含一个全面的 Makefile，其中包含用于开发任务的各种命令。每个命令都旨在简化开发工作流程并确保代码质量：

make all：按顺序运行 clean、lint 和 test（默认目标）
make clean：删除所有构建产物和临时文件
make test：使用 pytest 运行所有测试
- 可以使用环境变量进行配置：
  - LOG_LEVEL（默认：WARNING）- 控制测试输出的详细程度（DEBUG、INFO、WARNING、ERROR）
make unit-tests：仅运行带有详细输出的单元测试
- 可以使用环境变量进行配置：
  - LOG_LEVEL（默认：WARNING）- 控制测试输出的详细程度（DEBUG、INFO、WARNING、ERROR）
make integration-tests：仅运行带有详细输出的集成测试
- 可以使用环境变量进行配置：
  - YDB_ENDPOINT（默认：grpc://localhost:2136）
  - YDB_DATABASE（默认：/local）
  - MCP_HOST（默认：127.0.0.1）
  - MCP_PORT（默认：8989）
  - LOG_LEVEL（默认：WARNING）- 控制测试输出的详细程度（DEBUG、INFO、WARNING、ERROR）
make run-server：启动 YDB MCP 服务器
- 可以使用环境变量进行配置：
  - YDB_ENDPOINT（默认：grpc://localhost:2136）
  - YDB_DATABASE（默认：/local）
- 可以使用 ARGS="your args" 传递其他参数
make lint：运行所有 lint 检查（flake8、mypy、black、isort）
make format：使用 black 和 isort 格式化代码
make install：以开发模式安装包
make dev：以开发模式安装包并包含所有开发依赖项

测试详细程度控制

默认情况下，测试以最小输出（WARNING 级别）运行，以保持输出整洁。您可以使用 LOG_LEVEL 环境变量控制测试输出的详细程度：

# Run all tests with debug output
make test LOG_LEVEL=DEBUG

# Run integration tests with info output
make integration-tests LOG_LEVEL=INFO

# Run unit tests with warning output (default)
make unit-tests LOG_LEVEL=WARNING

可用的日志级别：

DEBUG：显示所有调试消息，对详细的测试流程很有用
INFO：显示信息性消息及以上级别
WARNING：仅显示警告和错误（默认）
ERROR：仅显示错误消息

Available Tools

7 tools

ydb_describe_pathC

Get detailed information about a YDB path

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It only states a read operation but does not describe error behavior (e.g., path not found), rate limits, or authentication requirements. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but under-informative. It lacks crucial details that could be added without significant length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has low complexity with one required parameter and an output schema, yet the description fails to explain what information is returned or any preconditions. It is incomplete for effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description adds no meaning to the 'path' parameter. It does not specify format, constraints, or examples. The parameter remains completely undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'detailed information about a YDB path', distinguishing it from sibling tools like 'ydb_list_directory' (lists directory contents) and 'ydb_explain_query' (explains queries). However, it lacks specificity about what 'detailed information' includes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or context. Usage is only implied by the tool's purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ydb_explain_queryC

Explain a SQL query against YDB

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose whether the query is executed or just planned, required permissions, or side effects. Basic behavioral traits like read-only nature are omitted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one sentence, five words). While efficient, it lacks necessary details. It is not verbose, but the conciseness comes at the cost of clarity. It barely meets the minimum threshold.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and low parameter coverage, the description is incomplete. It explains the basic purpose but omits key context such as the output format (though an output schema exists), prerequisites, or behavior. The agent may not be able to invoke correctly without additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for the 'sql' parameter. The description adds no extra meaning beyond the parameter type. It does not specify syntax, constraints, or examples, failing to compensate for the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool explains a SQL query against YDB. However, it does not differentiate from the sibling tool 'ydb_explain_query_with_params', which also explains queries but with parameters. The description should specify that this tool is for queries without parameters to avoid confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus the alternatives. There is no mention of when not to use it, such as for parameterized queries where 'ydb_explain_query_with_params' is more appropriate. The agent is left to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ydb_explain_query_with_paramsC

Explain a parameterized SQL query against YDB

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes
`params`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It states 'Explain', implying a read-only operation, but does not disclose any behavioral traits such as side effects, permissions, rate limits, or output format beyond what is in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous words. However, it is too brief and could include more essential information without being verbose. It is concise but at the expense of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of annotations and only 2 parameters, the description is insufficiently complete. It does not mention that both parameters are required, or provide context on how to supply parameters. An output schema exists but is not referenced.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage. The description does not explain the format or meaning of the 'params' parameter, which accepts a string or object. This lack of semantic guidance increases ambiguity for the AI agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses verb 'Explain' and specifies resource 'parameterized SQL query against YDB', which clearly indicates the tool's action and target. However, it does not differentiate from sibling tool 'ydb_explain_query' which likely does the same without parameters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs ydb_explain_query or other siblings. The description implies it is for queries with parameters but does not explicitly state when it should be preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ydb_list_directoryC

List directory contents in YDB

ParametersJSON Schema

Name	Required	Description	Default
`path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description bears full responsibility for behavioral disclosure. It only states the function without mentioning side effects, read-only nature, error handling, or recursion behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly brief at 4 words, lacking structure and essential details. It does not earn its place as it adds no value beyond the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple single-parameter schema and presence of an output schema, the description omits critical context such as return types, pagination, or behavior for nonexistent paths, making it insufficient for correct agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the format or semantics of the 'path' parameter (e.g., full vs relative path, supported patterns).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and resource 'directory contents', but does not differentiate from sibling tools like ydb_describe_path, which might also list path details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like ydb_describe_path or ydb_query. There is no context for typical use cases or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ydb_queryC

Run a SQL query against YDB database

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but fails to disclose safety traits (e.g., read-only vs mutation), idempotency, or side effects. It only says 'run a SQL query', which is insufficient for an agent to gauge risk.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise, but it is too terse given the lack of annotations and low schema coverage. Some additional context would be justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While an output schema exists (which helps with return values), the description omits important behavioral context such as safety, limits, or error conditions. For a tool that executes arbitrary SQL, more completeness is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only mentions 'SQL query' without elaborating on the 'sql' parameter's format, length constraints, or typical usage. The schema provides only type 'string'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('run a SQL query') and the resource ('YDB database'), but it does not differentiate from the sibling tool 'ydb_query_with_params', which presumably has similar functionality. The agent may be confused about when to use this one vs the other.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'ydb_query_with_params' or 'ydb_explain_query'. There is no mention of prerequisites, return handling, or selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ydb_query_with_paramsC

Run a parameterized SQL query with JSON parameters

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes
`params`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must fully disclose behavior. It only mentions JSON parameters but does not state if the query is executed (read/write), any limits, security implications, or whether results are returned. The behavioral transparency is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one short sentence), which is efficient but underspecified. It earns its place by being clear but lacks sufficient detail for a tool with no annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of parameterized SQL, no annotations, and an output schema, the description is incomplete. It does not mention return values (despite output schema existing), expected parameter formats, or relationship to sibling tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate. It mentions 'JSON parameters' but does not explain the 'sql' parameter or the expected format/structure of 'params'. The added meaning is minimal compared to what is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (run), resource (parameterized SQL query), and method (with JSON parameters). It distinguishes from siblings like ydb_query (likely non-parameterized) and ydb_explain_query_with_params (explain vs execute).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like ydb_query or ydb_explain_query_with_params. The description lacks any context about preferences, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ydb_statusA

Get the current YDB connection status

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states a read operation. It does not disclose whether the operation is safe, fast, or what happens on failure, but for a simple status check this minimal disclosure is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that is front-loaded and contains no unnecessary words, ideal for a simple status-check tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters and an output schema exists. The description covers the basic purpose but could be enhanced by clarifying what 'connection status' encompasses. Still, it is minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist and schema coverage is 100%, so the baseline of 3 applies. No additional parameter semantics are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and identifies the resource 'current YDB connection status', clearly distinguishing it from sibling tools that deal with path description, query execution, and directory listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The context of checking connectivity is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv0.1.4May 1, 2026

Changedydb_describe_path2 fields changed

changedInput schema / title

Previous value: -"describe_pathArguments"New value: +"ydb_describe_pathArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_describe_pathOutput",
+  "type": "object"
+}

Changedydb_explain_query3 fields changed

removedInput schema / properties / params

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Params"
-}

changedInput schema / title

Previous value: -"explain_queryArguments"New value: +"ydb_explain_queryArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_explain_queryOutput",
+  "type": "object"
+}

Changedydb_explain_query_with_params4 fields changed

addedInput schema / properties / params / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "additionalProperties": true,
+    "type": "object"
+  }
+]

removedInput schema / properties / params / type
```
Removed value: -"string"
```

changedInput schema / title

Previous value: -"explain_query_with_paramsArguments"New value: +"ydb_explain_query_with_paramsArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_explain_query_with_paramsOutput",
+  "type": "object"
+}

Changedydb_list_directory2 fields changed

changedInput schema / title

Previous value: -"list_directoryArguments"New value: +"ydb_list_directoryArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_list_directoryOutput",
+  "type": "object"
+}

Changedydb_query3 fields changed

removedInput schema / properties / params

Removed value: -{
-  "anyOf": [
-    {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "default": null,
-  "title": "Params"
-}

changedInput schema / title

Previous value: -"queryArguments"New value: +"ydb_queryArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_queryOutput",
+  "type": "object"
+}

Changedydb_query_with_params4 fields changed

addedInput schema / properties / params / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "additionalProperties": true,
+    "type": "object"
+  }
+]

removedInput schema / properties / params / type
```
Removed value: -"string"
```

changedInput schema / title

Previous value: -"query_with_paramsArguments"New value: +"ydb_query_with_paramsArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_query_with_paramsOutput",
+  "type": "object"
+}

Changedydb_status2 fields changed

changedInput schema / title

Previous value: -"get_connection_statusArguments"New value: +"ydb_statusArguments"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "Annotations": {
+      "additionalProperties": true,
+      "properties": {
+        "audience": {
+          "anyOf": [
+            {
+              "items": {
+                "enum": [
+                  "user",
+                  "assistant"
+                ],
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Audience"
+        },
+        "priority": {
+          "anyOf": [
+            {
+              "maximum": 1,
+              "minimum": 0,
+              "type": "number"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Priority"
+        }
+      },
+      "title": "Annotations",
+      "type": "object"
+    },
+    "TextContent": {
+      "additionalProperties": true,
+      "description": "Text content for a message.",
+      "properties": {
+        "_meta": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Meta"
+        },
+        "annotations": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Annotations"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null
+        },
+        "text": {
+          "title": "Text",
+          "type": "string"
+        },
+        "type": {
+          "const": "text",
+          "title": "Type",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type",
+        "text"
+      ],
+      "title": "TextContent",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "result": {
+      "items": {
+        "$ref": "#/$defs/TextContent"
+      },
+      "title": "Result",
+      "type": "array"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "ydb_statusOutput",
+  "type": "object"
+}

2 tool updatesv1.0.0Jan 2, 2026
- Addedydb_explain_query
- Addedydb_explain_query_with_params
5 tool updatesAug 14, 2025
- First observedydb_describe_path
- First observedydb_list_directory
- First observedydb_query
- First observedydb_query_with_params
- First observedydb_status

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored 2026-05-01 05:50 across 7 tools

Disambiguation5/5

Each tool has a distinct purpose: describing a path, explaining queries (with or without params), listing directory contents, running queries (with or without params), and checking status. No overlap or confusion.

Naming Consistency5/5

All tools follow a consistent 'ydb_<verb>' pattern with snake_case. The verb is specific and the 'with_params' suffix is applied uniformly for parameterized variants.

Tool Count5/5

Seven tools is well-scoped for a database query server. It covers query execution, query explanation, schema exploration, and status without being too sparse or bloated.

Completeness4/5

The tool set covers core read operations (query, explain, describe, list) and status. Missing write operations like insert or update, which may be intentional for a read-only server, but slightly limits completeness for full database interaction.

Maintenance

ActivityMaintained

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
mcp-aichatOAuth
io.github.AceDataCloud
MCP server for AI dialogue using various LLM models via AceDataCloud
AI & Machine Learning
2
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
Apideck MCP A
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42

Related MCP Servers

ClickHouse MCP Server
Databases RAG Systems Code Execution
ThomAub
A
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.
Updated 2 years ago (2024-12-18 18:34 UTC)
2
MIT
GreptimeDB MCP Serverofficial
Databases Code Execution
GreptimeTeam
A
license
A
quality
A
maintenance
A Model Context Protocol server implementation that enables AI assistants to securely interact with GreptimeDB, allowing them to explore database schema, read data, and execute SQL queries through a controlled interface.
Updated 2 days ago (2026-09-14 07:54 UTC)
15
29
MIT
Alibaba Cloud DMS MCP Serverofficial
Databases Data Platforms Developer Tools
aliyun
A
license
A
quality
B
maintenance
A Model Context Protocol server that enables large language models to access database metadata and perform cross-engine data querying across diverse database ecosystems.
Updated 2 months ago (2026-07-29 04:22 UTC)
16
52
Apache 2.0
@pilat/mcp-datalink
Databases Developer Tools
pilat
A
license
Not graded
quality
C
maintenance
MCP server for PostgreSQL, MySQL, and SQLite that gives AI assistants secure database access via the Model Context Protocol.
Updated 4 days ago (2026-09-12 13:31 UTC)
25 npm
4
MIT

Appeared in Searches

Database search and data processing tools

YDB MCP

使用方法

通过 uvx

示例：使用匿名身份验证

通过 pipx

示例：使用匿名身份验证

通过 pip

示例：使用匿名身份验证

身份验证

使用登录名/密码身份验证

使用访问令牌身份验证

使用服务账户身份验证

可用工具

构建自定义 MCP 服务器

为什么要构建自定义服务器？

可用方法

控制通用工具

示例

开发

可用 Make 命令

测试详细程度控制

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

GreptimeDB MCP Serverofficial

Alibaba Cloud DMS MCP Serverofficial

Appeared in Searches