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

YDB 用のModel Context Protocolサーバーです。MCPをサポートするあらゆるLLMからYDBデータベースを操作できます。この統合により、AIを活用したデータベース操作や、YDBインスタンスとの自然言語対話が可能になります。

使用方法

uvx経由

uv run toolのエイリアスであるuvxを使用すると、明示的にインストールすることなく様々な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を使い始めるには、YDBインスタンスと通信するようにMCPクライアントを設定する必要があります。以下に、セットアップに合わせてカスタマイズし、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接続の上に独自のツールを追加したり、必要に応じて組み込みの汎用ツールを無効にして、アプリケーションが必要とするクエリのみを公開したりできます。

なぜカスタムサーバーを構築するのか？

セキュリティ — 任意のSQL実行を許可するのではなく、読み取り専用クエリの固定セットにLLMを制限します。
ドメイン固有性 — 生のデータベースプリミティブではなく、ビジネスロジックに一致するツールをモデルに提供します。
シンプルさ — ツールが少ないほど、モデルにとっての曖昧さが減ります。

利用可能なメソッド

サブクラスでこれらをオーバーライドまたは呼び出します:

メソッド	説明
`await self.execute(sql, params=None)`	SQLクエリを実行します。`list[dict]`を返し、各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: すべてのリンティングチェックを実行します (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_queryB

Run a read-only SQL query against YDB database

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior3/5

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

The description discloses that the operation is 'read-only', which is a useful safety-related behavioral trait, especially since no annotations are provided. However, it does not mention return behavior, error cases, or limitations, so the description only partially carries the behavioral transparency burden.

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?

The description is a single focused sentence with no filler. It front-loads the action and resource, and every word contributes to meaning.

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, has an output schema to cover return values, and one obvious parameter, so the description is nearly adequate. However, it lacks any usage guidance relative to the sibling tools, leaving an important gap for correct tool selection.

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%, and the description does not explain the 'sql' parameter beyond implying it contains the query text. With only one required parameter, the gap is small, but the description still fails to explicitly document what the parameter should contain.

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 names a specific verb ('Run') and resource ('SQL query against YDB database'), clearly stating the tool's core purpose. However, it does not explicitly distinguish this from the sibling ydb_query_with_params, so sibling differentiation is absent.

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 given about when to use this tool instead of ydb_query_with_params, ydb_explain_query, or the other siblings. The description simply states what it does, leaving the agent to infer selection criteria from the tool name alone.

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 read-only 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

Behavior3/5

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

With no annotations, the description carries the behavioral burden. It clearly discloses the read-only nature of the operation, which is the most critical behavioral trait. However, it does not mention execution semantics, authentication, or error behavior, though the output schema covers result shape.

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

Conciseness4/5

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

The description is a single, front-loaded sentence with no filler. It is appropriately compact for the tool's simplicity, though it is terse enough that some semantic gaps remain.

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 lack of annotations, minimal parameter documentation, and presence of close sibling tools, the description is not complete enough for reliable selection and invocation. An agent would need to inspect other tools or examples to know when to choose this one and how to construct valid parameters.

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. It conveys that parameters are passed as JSON, which slightly clarifies the schema's anyOf string/object type, but it does not explain what 'sql' contains, how params map to query placeholders, or how JSON strings versus objects are handled.

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 states a clear action ('Run'), a specific resource ('read-only parameterized SQL query'), and the input format ('JSON parameters'). It mostly distinguishes itself from siblings like ydb_explain_query_with_params by indicating execution rather than explanation, though it doesn't explicitly name the non-parameterized alternative.

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 given about when to use this tool versus sibling tools such as ydb_query, ydb_explain_query, or ydb_explain_query_with_params. The agent is left to infer selection criteria from the name and one-line description.

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-09-24 03:05 across 7 tools

Disambiguation5/5

Each tool targets a clearly distinct purpose: executing vs explaining queries, with vs without parameters, and separate tools for status, directory listing, and path details. No two tools are ambiguous or likely to be confused during selection.

Naming Consistency4/5

All tools share the ydb_ prefix, and most follow a verb_noun pattern (list_directory, describe_path) with a consistent with_params modifier. Minor deviations like the noun-only ydb_status and ydb_query are still predictable and do not hinder readability.

Tool Count5/5

Seven tools is well-scoped for a database server focused on read-only operations, covering queries, explanations, status, and structural navigation without overflow or sparse coverage.

Completeness5/5

The server's read-only scope is fully covered: plain and parameterized queries, explain plans for both, connection status, and directory/path inspection. No obvious missing operations are needed for the intended use case.

Maintenance

ActivityMaintained

ResponsivenessResponsive

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 7 days ago (2026-09-23 10:00 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
54
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-26 11:32 UTC)
37 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