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 데이터베이스를 작업할 수 있게 해줍니다. 이 통합을 통해 YDB 인스턴스에 대한 AI 기반 데이터베이스 작업 및 자연어 상호작용이 가능해집니다.

사용법

uvx 사용

uv run tool의 별칭인 uvx를 사용하면 명시적으로 설치하지 않고도 다양한 파이썬 애플리케이션을 실행할 수 있습니다. 아래는 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 클라이언트 설정에 넣을 수 있는 구성 파일 예시입니다. 파이썬 인터프리터 경로는 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]`를 반환하며, 각 딕셔너리는 `"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