Skip to main content
Glama
kyokonishito

watsonx.data MCP Proxy

by kyokonishito
NOTE

まだテスト中です!

watsonx.data MCP Proxy

IBM watsonx.data Premium用のMCPプロキシサーバー。IBM watsonx.data remote Model Context Protocol (MCP) serverに接続し、IBM Cloud APIキーからアクセストークンを自動的に取得・更新してリクエストを中継します。

概要

このプロキシサーバーは、IBM watsonx.data Premiumのremote MCP server機能を利用するためのツールです。IBM Cloud IAMトークンの自動管理により、MCPクライアント(IBM BobやClaude Desktopなど)から簡単にwatsonx.dataのデータにアクセスできます。

Related MCP server: MCP OAuth Gateway

特徴

  • 自動トークン更新: IBM Cloud APIキーから自動的にトークンを取得し、期限切れ前に更新

  • MCPプロトコル対応: Model Context Protocol (MCP)に完全対応

  • 6つのツールをサポート: watsonx.dataのすべてのMCPツールに対応

  • エラーハンドリング: 堅牢なエラー処理とリトライロジック

  • ログ機能: 詳細なログでデバッグが容易

サポートされるツール

  1. LIST_DOCUMENT_LIBRARY - ドキュメントライブラリの一覧取得

  2. QUERY_DOCUMENT_LIBRARY - ドキュメントライブラリへのクエリ実行

  3. LIST_DOCUMENT_SET - ドキュメントセットの一覧取得

  4. QUERY_DOCUMENT_SET - ドキュメントセットへのクエリ実行

  5. LIST_DATA_ASSETS - データアセット(テーブル)の一覧取得

  6. QUERY_DATA_ASSETS - データアセットへのクエリ実行

インストール

前提条件

  • Python 3.10以上

  • pipx(推奨)またはpip

  • IBM Cloud APIキー

  • watsonx.data Premiumインスタンス

インストール方法

方法1: pipxでGitHubから直接インストール(推奨)

pipxを使用すると、独立した環境にインストールされ、システムのPython環境を汚染しません。

# pipxがインストールされていない場合
python -m pip install --user pipx
python -m pipx ensurepath

# GitHubから直接インストール
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

# 特定のブランチやタグからインストール
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git@main
pipx install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git@v0.1.0

方法2: pipでGitHubから直接インストール

# GitHubから直接インストール
pip install git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

# または、ユーザーディレクトリにインストール
pip install --user git+https://github.com/kyokonishito/watsonx_data_mcp_proxy.git

方法3: ローカル開発用(開発者向け)

# リポジトリをクローン
git clone https://github.com/kyokonishito/watsonx_data_mcp_proxy.git
cd watsonx_data_mcp_proxy

# uvで仮想環境を作成(推奨)
uv venv
source .venv/bin/activate  # Linux/macOS
# または .venv\Scripts\activate  # Windows

# 開発モードでインストール
uv pip install -e ".[dev]"

# または、pipを使用
pip install -e ".[dev]"

インストールの確認

# コマンドが利用可能か確認
watsonx-data-mcp-proxy --help

# または、Pythonモジュールとして実行
python -m watsonx_data_mcp_proxy --help

アンインストール

pipxでインストールした場合

pipx uninstall watsonx-data-mcp-proxy

pipでインストールした場合

pip uninstall watsonx-data-mcp-proxy

ローカル開発環境の場合

# 開発モードでインストールした場合
pip uninstall watsonx-data-mcp-proxy

# または、仮想環境ごと削除
rm -rf .venv

使用方法

IBM Bob (MCP Client)での設定

IBM Bobで使用する場合、.bob/mcp.jsonに設定を追加します。インストール方法に応じて設定が異なります。

方法1: pipxでインストールした場合(推奨)

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "watsonx-data-mcp-proxy",
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

方法2: ローカル開発環境の場合

仮想環境のPythonの絶対パスを指定します:

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

: プロジェクトが/Users/username/watsonx-data-mcp-proxyにある場合:

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/Users/username/watsonx-data-mcp-proxy/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

重要:

  • 環境変数は.bob/mcp.jsonenvセクションで設定するため、シェルで別途exportする必要はありません

  • ローカル開発環境では、必ず仮想環境のPythonの絶対パスを指定してください

  • pythonpython3などの相対コマンドは使用しないでください(モジュールが見つからないエラーが発生します)

Claude Desktop (MCP Client)での設定

Claude Desktopで使用する場合、設定ファイルの場所が異なります。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

方法1: pipxでインストールした場合(推奨)

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "watsonx-data-mcp-proxy",
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

方法2: ローカル開発環境の場合

{
  "mcpServers": {
    "watsonx-data-premium": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "watsonx_data_mcp_proxy"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-ibm-cloud-api-key",
        "WATSONX_DATA_URL": "https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
      }
    }
  }
}

サーバーの起動

IBM BobまたはClaude Desktopを起動すると、自動的にプロキシサーバーが起動します。トークンは自動的に取得・更新されます。

手動でテストする場合(開発時のみ):

export IBM_CLOUD_API_KEY="your-ibm-cloud-api-key"
export WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
python -m watsonx_data_mcp_proxy

設定オプション

トークン更新マージン

デフォルトでは、トークンの有効期限の5分前に自動更新されます。この値はTokenManagerクラスのrefresh_marginパラメータで変更できます。

ログレベル

環境変数LOG_LEVELでログレベルを設定できます:

export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR, CRITICAL

開発

テストの実行

# すべてのテストを実行
pytest

# カバレッジレポート付きで実行
pytest --cov=src/watsonx_data_mcp_proxy --cov-report=html

# 特定のテストファイルのみ実行
pytest tests/test_token_manager.py

# 統合テストを実行(実際のwatsonx.dataに接続)
# 環境変数を設定して実行
export IBM_CLOUD_API_KEY="your-ibm-cloud-api-key"
export WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/"
pytest tests/test_integration.py -v -m integration

# または、uv仮想環境を使用する場合
IBM_CLOUD_API_KEY="your-api-key" WATSONX_DATA_URL="https://your-instance.lakehouse.saas.ibm.com/api/v2/mcp/" uv run pytest tests/test_integration.py -v -m integration

# LIST_DATA_ASSETSテストを実行する場合(追加の環境変数が必要)
export WATSONX_DATA_CONTAINER_ID="your-container-id"
export WATSONX_DATA_PRESTO_CRN="your-presto-instance-crn"
export WATSONX_DATA_PRESTO_ENGINE_ID="your-presto-engine-id"
pytest tests/test_integration.py::test_list_data_assets -v -s

テストの種類

  1. ユニットテスト (test_token_manager.py, test_server.py)

    • モックを使用した単体テスト

    • 高速で依存関係なし

  2. 統合テスト (test_integration.py)

    • 実際のIBM Cloudとwatsonx.dataに接続

    • 環境変数の設定が必要

プロジェクト構造

mcp_wxd_premium/
├── src/
│   └── watsonx_data_mcp_proxy/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py          # MCPサーバー実装
│       └── token_manager.py   # トークン管理
├── tests/
│   ├── test_token_manager.py  # トークン管理のテスト
│   ├── test_server.py         # サーバーのテスト
│   └── test_integration.py    # 統合テスト
├── .bob/
│   └── mcp.json              # IBM Bob設定ファイル
├── pyproject.toml            # プロジェクト設定
└── README.md                 # このファイル

トラブルシューティング

トークン取得エラー

RuntimeError: IBM Cloudトークンの取得に失敗しました

解決方法:

  • IBM Cloud APIキーが正しいか確認

  • APIキーに適切な権限があるか確認

  • ネットワーク接続を確認

watsonx.data接続エラー

RuntimeError: watsonx.dataへのリクエストが失敗しました

解決方法:

  • watsonx.data URLが正しいか確認

  • watsonx.dataインスタンスでMCPサーバー機能が有効化されているか確認

  • トークンに適切な権限があるか確認

レスポンス形式エラー

Invalid response format: 'rows' is not a string []

解決方法:

  • watsonx.dataのMCPサーバーバージョンを確認

  • プロキシサーバーのログを確認してレスポンス内容を調査

ライセンス

このプロジェクトはApache License 2.0の下でライセンスされています。詳細はLICENSEファイルを参照してください。

参考資料

Available Tools

6 tools
LIST_DATA_ASSETSC

提供された接続パラメータに基づいてフィルタリングされたPrestoテーブルを返します

ParametersJSON Schema
NameRequiredDescriptionDefault
container_idYesコンテナID
container_typeYesコンテナタイプ
presto_engine_idYesPrestoエンジンID
presto_instance_crnYesPrestoインスタンスCRN

TDQS

C2.9/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 the full behavioral burden. It implies a read-only listing but does not disclose pagination, result size limits, authorization requirements, or what happens when the connection parameters match nothing.

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?

A single tight sentence with the action and filter basis front-loaded and no wasted words. Its brevity is appropriate, though there is nothing else to front-load because the sentence contains so little.

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?

This is a four-required-parameter tool with no annotations and no output schema, meaning the description should explain the shape of the returned Presto tables and any filtering behavior. It provides neither, and also leaves ambiguity around whether all four connection parameters are mandatory.

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?

Schema description coverage is 100%, so all four parameters (container_id, container_type, presto_engine_id, presto_instance_crn) are already documented in the schema. The description only alludes to 'connection parameters' generally and adds no format, constraint, or relationship detail beyond the schema, which is the expected baseline.

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 specific verb (returns/list) and resource (Presto tables) plus the filtering basis (provided connection parameters), so the core action is unambiguous. However, it does not distinguish this tool from the sibling QUERY_DATA_ASSETS, so an agent cannot tell from the text alone which data-asset tool to pick.

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?

There is no guidance on when to call LIST_DATA_ASSETS versus QUERY_DATA_ASSETS, nor any mention of prerequisites such as having a valid Presto instance CRN or engine ID. The agent must infer usage conditions entirely from the name.

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

LIST_DOCUMENT_LIBRARYB

すべての利用可能なドキュメントライブラリとそのメタデータをリストします

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations, the description carries the full behavioral burden, and it discloses little beyond the basic act of listing. It does not state that this is a safe read-only operation, nor whether results are paginated, how metadata is shaped, or any auth/size constraints. It adds minimal behavioral context for a no-annotation tool.

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, front-loaded sentence that states verb, resource, scope, and return content with no redundancy or filler. Appropriately sized for the tool's simplicity.

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?

For a zero-parameter read tool the completeness bar is modest, but with no annotations and no output schema the definition should say more about the response (e.g. pagination, metadata fields, empty-list behavior). It covers the core purpose but leaves the return contract unspecified.

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

Parameters4/5

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

The tool takes zero parameters, so the baseline is 4. The description does add one semantic point beyond the empty schema: it returns all available libraries with their metadata and applies no filtering, which is useful context for an agent expecting an unfiltered enumeration.

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 specific verb (リストします/list) and resource (ドキュメントライブラリ/document libraries) plus what is returned (そのメタデータ/metadata), so the purpose is clear. However, it does not distinguish itself from the sibling QUERY_DOCUMENT_LIBRARY, leaving the agent to infer the list-vs-query split on its own.

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

Usage Guidelines3/5

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

No explicit when-to-use or when-not-to-use guidance is given, and no alternative (e.g. QUERY_DOCUMENT_LIBRARY) is named. The qualifier 「すべての利用可能な」 (all available) weakly implies this is the enumerate-everything variant, which is only implied usage rather than stated context.

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

LIST_DOCUMENT_SETC

指定されたドキュメントライブラリ内のすべてのドキュメントセットとそのメタデータをリストします

ParametersJSON Schema
NameRequiredDescriptionDefault
library_idYesドキュメントライブラリID

TDQS

C2.9/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 the full behavioral burden. 'Lists' implies a read-only, non-destructive operation and the description does state that metadata is returned, but it says nothing about pagination, result limits, ordering, or permission requirements for a potentially large collection.

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?

A single well-formed sentence that front-loads the action and scope with no filler. It is appropriately sized for a simple listing tool, though there is room for one more sentence of routing guidance.

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?

For a one-parameter list tool with no output schema, the description covers what is listed and where, which is the core need. It falls short on pagination/result-size behavior and on distinguishing itself from the QUERY_DOCUMENT_SET sibling, both of which matter in a five-sibling family.

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?

Schema description coverage is 100% for the single library_id parameter, so the schema already documents the parameter's meaning. The description reinforces that the listing is scoped to the specified library but adds no format or constraint details beyond that. Baseline 3 applies when the schema does the heavy lifting.

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 uses a specific verb (リストします) and resource (ドキュメントセット) with explicit scope (指定されたドキュメントライブラリ内) and even notes that metadata is included. It is clearly distinguishable from LIST_DOCUMENT_LIBRARY, but it never explicitly contrasts itself with the sibling QUERY_DOCUMENT_SET, leaving the read-vs-query distinction implicit.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives such as QUERY_DOCUMENT_SET or QUERY_DOCUMENT_LIBRARY. The only usage hint is that results are scoped to a specified library, which is inferable from the required parameter rather than stated explicitly.

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

QUERY_DATA_ASSETSB

選択されたPrestoテーブルに対して自然言語クエリを実行します

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes自然言語クエリ
tablesYesクエリ対象のテーブルリスト
container_idYesコンテナID
container_typeYesコンテナタイプ
presto_engine_idYesPrestoエンジンID
presto_instance_crnYesPrestoインスタンスCRN

TDQS

B3.1/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 behavioral burden. It does not state whether the operation is read-only, what permissions are required, whether the natural language is interpreted locally or remotely, or what the response contains. Only the basic action is described.

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, front-loaded sentence with no filler. It is appropriately sized for a minimal description, though it is arguably under-specified rather than over-concise.

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?

For a 6-parameter query tool with no annotations and no output schema, the description is incomplete. It does not explain what the natural language query returns, how results are structured, or any prerequisites, leaving the agent to infer everything beyond the purpose.

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?

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description adds no additional meaning about parameter formats, constraints, or relationships (e.g., tables must belong to the container). Baseline 3 is appropriate.

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 specific verb (executes) and resource (natural language query against selected Presto tables), which distinguishes it from the document-oriented siblings (QUERY_DOCUMENT_LIBRARY, QUERY_DOCUMENT_SET). However, it does not differentiate from LIST_DATA_ASSETS or clarify what a 'data asset' is in this context.

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 when-to-use guidance is provided, no prerequisites are mentioned (e.g., needing a Presto instance or engine already configured), and no alternatives are suggested (e.g., listing assets first with LIST_DATA_ASSETS).

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

QUERY_DOCUMENT_LIBRARYC

指定されたドキュメントライブラリに対して自然言語クエリを実行します

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes自然言語クエリ
library_idYesドキュメントライブラリID

TDQS

C2.9/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 the full burden and says nothing about behavior. It does not state that the operation is read-only, whether the query costs money/is rate-limited, what auth is required, or what a result looks like.

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?

A single front-loaded sentence with no wasted words, appropriate for a two-parameter tool. It is short but not padded or repetitive.

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?

For a simple two-parameter read-style tool with a fully documented schema, the description covers the basic purpose. However, with no annotations and no output schema, the absence of any behavioral or usage context leaves it only 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?

Schema description coverage is 100%, with both query and library_id documented inline, so the baseline is 3. The description adds no extra meaning (no format, syntax, or example of a natural-language query) beyond what the schema already provides.

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 specific verb (実行します) and resource (指定されたドキュメントライブラリ) with a clear scope (natural-language query). It is distinguishable from the LIST_* siblings, but it never distinguishes itself from the near-identical QUERY_DOCUMENT_SET sibling, so full sibling differentiation is missing.

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?

There is no guidance on when to use this over LIST_DOCUMENT_LIBRARY or QUERY_DOCUMENT_SET, nor any prerequisite or exclusion information. The agent must infer usage entirely from the name.

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

QUERY_DOCUMENT_SETC

指定されたドキュメントセットに対して自然言語クエリを実行します

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes自然言語クエリ
set_idYesドキュメントセットID
library_idYesドキュメントライブラリID

TDQS

C2.9/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 the full behavioral burden. It implies a read/query operation but does not state that it is non-destructive, what the query returns, whether results are paginated or ranked, or any permission requirements.

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?

A single, front-loaded sentence with no waste. It is appropriately sized for what it conveys, though it is arguably under-specified rather than optimally concise.

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?

With three required parameters, no annotations, and no output schema, the description should explain at least the nature of the query results and its read-only character. It does neither, leaving the agent to guess at behavior for a tool whose return value is the whole point.

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?

Schema description coverage is 100%, and each of the three parameters already has a short Japanese description in the schema. The tool description adds no meaning beyond those labels, so the baseline 3 for fully documented parameters applies.

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 (自然言語クエリを実行) and resource (指定されたドキュメントセット), so the agent knows it runs an NL query against a document set. It does not, however, explicitly distinguish itself from the sibling QUERY_DOCUMENT_LIBRARY, which shares nearly identical phrasing.

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?

There is no guidance on when to choose this over QUERY_DOCUMENT_LIBRARY or LIST_DOCUMENT_SET, nor any prerequisite or exclusion stated. The agent must infer usage purely from the tool name.

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.

  1. 6 tool updatesv0.1.0
    • First observedLIST_DATA_ASSETS
    • First observedLIST_DOCUMENT_LIBRARY
    • First observedLIST_DOCUMENT_SET
    • First observedQUERY_DATA_ASSETS
    • First observedQUERY_DOCUMENT_LIBRARY
    • First observedQUERY_DOCUMENT_SET

TDQS

A3.5/5.0

Scored across 6 tools

Disambiguation5/5

The six tools form clear LIST/QUERY pairs for three distinct resource levels: document libraries, document sets, and Presto data assets. Each tool's target and action are unambiguous, and the hierarchical relationship between library and set is explicit.

Naming Consistency5/5

All tool names follow a consistent uppercase snake_case VERB_NOUN pattern (LIST_* or QUERY_* followed by the resource). There is no mixing of conventions.

Tool Count5/5

Six tools is well-scoped for a query proxy: three resource types each get exactly a list and query operation. No tool feels redundant or missing for the basic query surface.

Completeness4/5

The surface covers discovery and natural-language querying for document libraries, document sets, and Presto tables. However, it lacks any create/update/delete or ingestion operations, and there is no direct way to list individual documents within a set, so management workflows would hit gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

  • Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.

  • The BigQuery remote MCP server is a fully managed service that uses the Model Context Protocol to connect AI applications and LLMs to BigQuery data sources. It provides secure, standardized tools for AI agents to list datasets and tables, retrieve schemas, generate and execute SQL queries through natural language, and analyze data—enabling direct access to enterprise analytics data without requiring manual SQL coding.

  • The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.

  • MCP server connecting AI agents to non-custodial staking data across 130+ networks.

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides secure integration between MCP clients and IBM Data Intelligence services, enabling AI assistants to interact with IBM's data intelligence capabilities for data management and analytics operations.
    Apache 2.0
  • A
    license
    Not graded
    quality
    D
    maintenance
    A transparent proxy server that simplifies authentication by chaining its own OAuth layer with an upstream MCP server's credentials. It manages dual token sets behind a single interface, enabling secure and streamlined access to protected MCP resources.
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    A proxy server that connects MCP clients to the Zihin.ai platform via HTTP, enabling management of AI agents, LLM models, and configuration templates. It provides tools for agent creation and resources for discovering tenant-specific agents and schema templates.
    96
    408 npm
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Provides a modular MCP server to integrate with IBM Data Intelligence services, enabling secure interaction with data intelligence capabilities via tools and skills.
    19
    Apache 2.0