Skip to main content
Glama
enesjakozh
husamabusafa

Advanced Hasura GraphQL MCP Server

by husamabusafa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

高度な Hasura GraphQL MCP サーバー

バージョン: 1.1.0

このモデルコンテキストプロトコル（MCP）サーバーは、AIエージェント（CursorやClaude Desktopなど）がHasura GraphQLエンドポイントと対話するための高度なインターフェースを提供します。エージェントは、API構造の検出、読み取り専用クエリとミューテーション（注意して実行）、データのプレビュー、集計の実行、サービスの健全性チェックなどを行うことができます。

このサーバーは、自然言語のリクエストに基づいて Hasura API を動的に活用できるようにすることで、LLM 機能を強化します。

特徴

このサーバーは、次の MCP 機能を公開します。

リソース：

  • Hasura GraphQL スキーマ ( hasura:/schema )

    • 標準のイントロスペクションによって取得された完全な GraphQL スキーマ定義を提供します。

    • MIMEタイプ: application/json

    • エージェントはこのリソースを読んで、型、フィールド、引数、ディレクティブなどを含む API の完全な構造を理解できます。

ツール:

  • run_graphql_query

    • 説明: Hasuraエンドポイントに対して読み取り専用のGraphQLクエリを実行します。特定のツールが利用できない場合にデータを取得するために使用します。クエリによってデータが変更されないようにしてください。例: query { users { id name } }

    • 入力: { query: string, variables?: object }

    • 注: mutationで始まる文字列の実行を防ぐための基本的なチェックを実行します。主にクエリ自体が読み取り専用であることを前提としています。

  • run_graphql_mutation

    • 説明: GraphQLミューテーションを実行して、データを挿入、更新、または削除します。操作が意図されたものであり、安全であることを確認した上で、慎重に使用してください。指定された管理者シークレットまたはデフォルトのロールに設定されたHasura権限に依存します。例: mutation { insert_users_one(object: {name: "Test"}) { id } }

    • 入力: { mutation: string, variables?: object }

    • セキュリティ: Hasuraロールで許可されたすべての変更を許可します。適切なHasura権限が設定されていることを確認してください。

  • list_tables

    • 説明: Hasura によって管理されている利用可能なデータテーブル（またはコレクション）を、イントロスペクションヒューリスティック（内部/集約型を除く、「id」フィールドを持つオブジェクト型を検索）に基づいて、スキーマと説明ごとに整理して一覧表示します。利用可能なデータソースの検出に役立ちます。

    • 入力: { schemaName?: string } (オプションのスキーマ名、可能な場合はフィールドの説明から推測を試みます。概念的にはデフォルトは「public」です)

  • describe_table

    • **説明:**特定のテーブルの構造を、そのすべての列 (フィールド) とその GraphQL タイプおよび説明とともに表示します。

    • 入力: { tableName: string, schemaName?: string }

  • list_root_fields

    • 説明: GraphQLスキーマから利用可能な最上位レベルのクエリ、ミューテーション、またはサブスクリプションフィールドを一覧表示します。操作の主要なエントリポイントを理解するのに役立ちます。

    • 入力: { fieldType?: 'QUERY' | 'MUTATION' | 'SUBSCRIPTION' } (オプションのフィルター)

  • describe_graphql_type

    • **説明:**スキーマイントロスペクションを用いて、特定のGraphQL型（オブジェクト、入力、スカラー、列挙型、インターフェース、ユニオン）の詳細を提供します。特定の型を含むクエリやミューテーションの構造化方法を理解する上で不可欠です。

    • 入力: { typeName: string } (大文字と小文字を区別する型名)

  • preview_table_data

    • **説明:**指定されたテーブルから限られた行数（デフォルトは5行）のサンプルを取得し、そのデータ構造と内容をプレビューします。共通のスカラーフィールドと列挙型フィールドは自動的に選択されます。

    • 入力: { tableName: string, limit?: number }

  • aggregate_data

    • **説明:**指定されたテーブルに対して、単純な集計（count、sum、avg、min、max）を実行します。オプションでHasuraの「where」フィルターを適用できます。テーブル名を検索するには「list_tables」を使用してください。count以外の集計には「field」が必要です。

    • 入力: { tableName: string, aggregateFunction: 'count'|'sum'|'avg'|'min'|'max', field?: string, filter?: object }

  • health_check

    • **説明:**設定されたHasura GraphQLエンドポイントが到達可能であり、基本的なGraphQLクエリ( { __typename } )に応答するかどうかを確認します。オプションで、特定のHTTPヘルスエンドポイントURLがわかっている場合は、そのURLをチェックすることもできます。

    • 入力: { healthEndpointUrl?: string } (オプションの特定のヘルス URL)

Related MCP server: GraphQL MCP Toolkit

要件

  • Node.js (v18 以上を推奨、指定されている場合は.nvmrcまたはpackage.json enginesを確認してください)

  • pnpm (またはnpm / yarn 、コマンドは適宜調整してください)

  • 実行中の Hasura GraphQL エンドポイントへのアクセス。

  • (オプションですが推奨) 特権アクセス用の Hasura 管理者シークレット、または適切に構成されたデフォルトのロール権限。

セットアップとインストール

  1. リポジトリをクローンします (該当する場合)。

    # git clone <repository_url>
# cd mcp-hasura-advanced

  2. 依存関係をインストールします:

    pnpm install

  3. サーバーを構築する:

    pnpm run build

    これにより、TypeScript コードがdistディレクトリにコンパイルされます。

サーバーの実行

Hasura エンドポイント URL とオプションで管理者シークレットを指定して、ターミナルからコンパイルされたスクリプトを実行します。

# Using pnpm start script (defined in package.json)
pnpm start <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

# Or using Node directly
node dist/index.js <HASURA_GRAPHQL_ENDPOINT> [ADMIN_SECRET]

例：

pnpm start https://my-hasura.cloud/v1/graphql mysecretkey123

または

node dist/index.js https://my-hasura.cloud/v1/graphql mysecretkey123

管理者シークレットが必要ない場合（デフォルトのロール権限を使用）：

pnpm start https://my-hasura.cloud/v1/graphql

サーバーが起動し、初期のスキーマイントロスペクションを試行し、STDIOトランスポートに接続し、ステータスメッセージをstderrに記録します。stdin stdin MCP JSON-RPCリクエストをリッスンし、 stdoutに応答を送信します。

MCP クライアント (例: Cursor、Claude Desktop) での使用

このサーバーを Cursor などの MCP クライアントに接続するには:

  1. 絶対パスを見つける:

    • ノード実行ファイル: ターミナルでwhich nodeを実行します。

    • サーバースクリプト: mcp-hasura-advancedディレクトリに移動し、 pwdを実行します。結果に/dist/index.jsを追加します。

    • プロジェクト ディレクトリ: pwdの出力。

  2. **クライアントを構成する:**クライアントの構成ファイルを開きます (例: Cursor の場合はsettings.json 、Claude Desktop の場合はclaude_desktop_config.json )。

  3. **サーバー エントリの追加:**適切なキーの下にエントリを追加します (例: Cursor の場合はcursor.customMcpServers配列、Claude Desktop の場合はmcpServersオブジェクト)。

カーソルsettings.json例.json:

{
  // ... other settings ...
  "cursor.customMcpServers": [
    // ... other servers ...
    {
      "name": "My Advanced Hasura Server", // Name shown in Cursor UI
      "command": "/path/to/your/node", // <<< Absolute path from 'which node'
      "args": [
        "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to compiled script
        "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< Your endpoint
        "YOUR_ADMIN_SECRET"                                   // <<< Your secret (REMOVE if no secret)
      ],
      // Optional but recommended for module resolution consistency:
      "cwd": "/absolute/path/to/mcp-hasura-advanced" // <<< Absolute path to project root
    }
  ]
}

Claude Desktop の例claude_desktop_config.json :

{
    "mcpServers": {
        // ... other servers ...
        "hasura-advanced": { // Key used internally by Claude
            "command": "/path/to/your/node", // <<< Absolute path from 'which node'
            "args": [
                "/absolute/path/to/mcp-hasura-advanced/dist/index.js", // <<< Absolute path to compiled script
                "https://YOUR_HASURA_ENDPOINT.com/v1/graphql",      // <<< Your endpoint
                "YOUR_ADMIN_SECRET"                                   // <<< Your secret (REMOVE if no secret)
            ],
            // Optional:
            // "cwd": "/absolute/path/to/mcp-hasura-advanced"
        }
    }
}

  1. **プレースホルダーの置き換え:**すべてのプレースホルダー ( /path/to/... 、 https://YOUR... 、 YOUR_ADMIN_SECRET ) を実際の値に更新します。

  2. **クライアントの再起動/リロード:**構成を保存し、MCP クライアント アプリケーションを再起動またはリロードします。

  3. **サーバーの選択:**クライアントの UI で「My Advanced Hasura Server」(または指定した名前) を選択します。

  4. **対話:**クライアントのチャットで自然言語プロンプトを使用して、サーバーのツールを活用します (例: 「Hasura サーバーを使用してテーブルを一覧表示する」、「「users」テーブルについて説明する」、「「orders」テーブルからデータをプレビューする」、「Hasura サーバーを使用してクエリ{ products { name price } }を実行する」)。

発達

  • 開発モードで実行: pnpm run dev <ENDPOINT> [SECRET]を使用して、 ts-nodeでサーバーを直接実行し、反復処理を高速化します (ビルド ステップは不要)。

  • **テスト:**サーバーを手動で実行し ( pnpm start ... )、JSON-RPC リクエストをstdinにパイプして、個々のツールをテストします。

Available Tools

9 tools
aggregate_dataC

Performs a simple aggregation (count, sum, avg, min, max)...

ParametersJSON Schema
NameRequiredDescriptionDefault
aggregateFunctionYesThe aggregation function...
fieldNoRequired for 'sum', 'avg', 'min', 'max'...
filterNoOptional. A Hasura GraphQL 'where' filter object...
tableNameYesThe exact name of the table...

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions 'simple aggregation' but doesn't clarify permissions needed, rate limits, whether it's read-only or has side effects, or what the output format looks like. For a data querying tool with zero annotation coverage, this leaves significant behavioral gaps.

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 extremely concise - a single sentence fragment that gets straight to the point. Every word earns its place by specifying the core functionality without any fluff or redundant information.

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?

For a data aggregation tool with 4 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, how results are formatted, error conditions, or provide enough context for an agent to understand the full scope of this operation beyond the basic function listing.

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 the schema already documents all four parameters thoroughly. The description adds minimal value by listing the aggregation functions but doesn't provide additional context about parameter interactions or usage patterns beyond what's in the schema descriptions.

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 tool performs aggregation operations (count, sum, avg, min, max) on data, which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'preview_table_data' or 'run_graphql_query' that might also access data, leaving some ambiguity about when to choose this specific aggregation tool.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'run_graphql_query' that might handle similar data operations, nor does it specify prerequisites or contexts where aggregation is preferred over other data retrieval methods.

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

describe_graphql_typeC

Provides details about a specific GraphQL type (Object, Input, Scalar, Enum, Interface, Union)...

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNameYesThe exact, case-sensitive name of the GraphQL type...

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 full burden for behavioral disclosure. The description only states what the tool does ('Provides details'), but doesn't disclose any behavioral traits such as whether it's a read-only operation, what format the details are provided in, error handling, performance characteristics, or authentication requirements. For a tool with zero annotation coverage, this is a significant gap.

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 extremely concise - a single sentence that efficiently communicates the core function. It's front-loaded with the main purpose and includes useful enumeration of type categories without unnecessary elaboration. Every word earns its place with no wasted text.

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 and output schema, the description is incomplete for a tool that presumably returns structured data about GraphQL types. It doesn't indicate what 'details' are provided (fields, descriptions, interfaces, etc.), the format of the response, or any limitations. For a tool that likely returns complex type information, this leaves significant gaps for an AI agent.

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 the schema already fully documents the single parameter 'typeName'. The description doesn't add any parameter semantics beyond what's in the schema - it doesn't explain what constitutes a valid type name beyond 'specific GraphQL type', provide examples, or clarify the relationship between type categories and the parameter. Baseline 3 is appropriate when 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 clearly states the tool's purpose: 'Provides details about a specific GraphQL type' with explicit enumeration of the type categories (Object, Input, Scalar, Enum, Interface, Union). It uses a specific verb ('Provides details') and identifies the resource ('GraphQL type'), but doesn't explicitly differentiate from sibling tools like 'list_root_fields' or 'run_graphql_query' which might also provide type-related information.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'list_root_fields' (which might list types) or 'run_graphql_query' (which might return type information indirectly), nor does it specify prerequisites or appropriate contexts for usage beyond the basic function.

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

describe_tableB

Shows the structure of a table including all columns with their types and descriptions

ParametersJSON Schema
NameRequiredDescriptionDefault
schemaNameNoOptional. The database schema name, defaults to 'public'public
tableNameYesThe exact name of the table to describe

TDQS

B3.2/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden but lacks behavioral details. It doesn't disclose whether this is a read-only operation, what permissions are required, how errors are handled, or the format of the returned structure. The description is minimal beyond stating the output content.

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, efficient sentence that front-loads the core purpose without unnecessary words. Every part of the sentence contributes directly to understanding the tool's function.

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 no output schema, the description is incomplete for a tool that returns structural metadata. It doesn't explain the return format, error conditions, or behavioral traits, leaving significant gaps for an agent to use it correctly.

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 the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as examples or constraints. Baseline 3 is appropriate when 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 clearly states the verb 'shows' and the resource 'structure of a table', specifying what information is included (columns with types and descriptions). It distinguishes from siblings like list_tables (which lists table names) and preview_table_data (which shows actual data), though not explicitly named.

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?

The description implies usage when needing table metadata rather than data or schema listings, but doesn't explicitly state when to use this tool versus alternatives like list_tables or preview_table_data. No exclusions or prerequisites are mentioned.

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

health_checkC

Checks if the configured Hasura GraphQL endpoint is reachable...

ParametersJSON Schema
NameRequiredDescriptionDefault
healthEndpointUrlNoOptional. A specific HTTP health check URL...

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 of behavioral disclosure. It mentions checking reachability but doesn't specify what 'reachable' entails (e.g., HTTP status codes, timeouts, authentication requirements). For a diagnostic tool with zero annotation coverage, this leaves critical behavioral traits like error handling or performance implications unclear.

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, efficient sentence that directly states the tool's purpose without unnecessary details. It's appropriately sized and front-loaded, though it could be slightly more structured by including usage hints. Overall, it earns its place without waste.

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 tool's diagnostic nature and lack of annotations or output schema, the description is incomplete. It doesn't explain what the check entails (e.g., network connectivity, endpoint response validation) or what results to expect (e.g., success/failure indicators). For a tool with no structured output documentation, more context is needed to guide effective use.

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 the schema already documents the single parameter 'healthEndpointUrl' with its description and format. The description doesn't add any meaning beyond what the schema provides, such as explaining default behavior when the parameter is omitted. Baseline 3 is appropriate when the schema handles parameter documentation adequately.

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 tool's purpose: 'Checks if the configured Hasura GraphQL endpoint is reachable...' This specifies the verb ('checks') and resource ('Hasura GraphQL endpoint'), though it doesn't explicitly differentiate from siblings like 'run_graphql_query' which might also test connectivity indirectly. The purpose is clear but lacks sibling differentiation.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing a configured endpoint, or compare it to siblings like 'run_graphql_query' that might serve similar diagnostic purposes. Without such context, users must infer usage scenarios.

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

list_root_fieldsC

Lists the available top-level query, mutation, or subscription fields...

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldTypeNoOptional. Filter by 'QUERY'...

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 full burden. It mentions listing fields but doesn't disclose behavioral traits such as whether this is a read-only operation, if it requires authentication, rate limits, or what the output format looks like (e.g., list of strings, structured data). This is a significant gap for a tool with zero annotation coverage.

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, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly.

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

Completeness2/5

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

Given the complexity of GraphQL operations and lack of annotations or output schema, the description is incomplete. It doesn't explain what 'available' means (e.g., based on permissions), how results are returned, or provide context for the sibling tools, leaving gaps in understanding the tool's full behavior.

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 the schema already documents the single optional parameter 'fieldType' with its enum values. The description implies filtering by field type but doesn't add any syntax, format, or usage details beyond what the schema provides, resulting in a baseline score of 3.

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 action ('Lists') and the resource ('available top-level query, mutation, or subscription fields'), making the purpose understandable. However, it doesn't explicitly differentiate from siblings like 'describe_graphql_type' or 'run_graphql_query', which might also involve GraphQL operations, so it misses full sibling distinction.

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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like exploring GraphQL schema, comparing to 'describe_graphql_type' for detailed field info, or using 'run_graphql_query' for actual queries, leaving the agent with no usage context.

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

list_tablesA

Lists available data tables (or collections) managed by Hasura, organized by schema with descriptions

ParametersJSON Schema
NameRequiredDescriptionDefault
schemaNameNoOptional. The database schema name to filter results. If omitted, returns tables from all schemas.

TDQS

A3.5/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It mentions organization by schema with descriptions, which adds context beyond a basic list. However, it lacks details on behavioral traits such as pagination, rate limits, authentication needs, or what 'available' means (e.g., permissions). The description does not contradict annotations (none exist).

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, efficient sentence that front-loads the core purpose ('Lists available data tables') and adds useful context ('organized by schema with descriptions'). There is no wasted verbiage or redundancy, making it appropriately sized for its function.

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?

Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is moderately complete. It covers the purpose and organization but lacks details on output format (e.g., structure of returned data), error handling, or integration with siblings. Without an output schema, more guidance on return values would be beneficial.

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 the parameter 'schemaName' fully documented in the schema as an optional filter. The description does not add any parameter-specific details beyond what the schema provides, such as format examples or default behavior when omitted. Baseline 3 is appropriate as the schema handles 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 clearly states the action ('Lists') and resource ('available data tables (or collections) managed by Hasura'), specifying organization by schema with descriptions. It distinguishes from siblings like 'describe_table' (detailed metadata) and 'preview_table_data' (data viewing), though not explicitly named. However, it could be more specific about what 'lists' entails (e.g., names, counts).

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?

The description implies usage for browsing tables by schema, but does not explicitly state when to use this tool versus alternatives like 'describe_table' (for detailed info) or 'list_root_fields' (for GraphQL endpoints). No guidance on prerequisites or exclusions is provided, leaving usage context inferred rather than defined.

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

preview_table_dataB

Fetch esa limited sample of rows (default 5) from a specified table...

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoOptional. Maximum number of rows...
tableNameYesThe exact name of the table...

TDQS

B3.3/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden. It mentions the default limit of 5 rows, which is useful behavioral context. However, it lacks details on permissions needed, error handling (e.g., if table doesn't exist), or response format (e.g., structure of returned rows), leaving gaps for a tool that fetches data.

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, efficient sentence that front-loads the core purpose ('fetch esa limited sample of rows') and includes key details (default limit, table specification). There is no wasted text, making it highly concise and well-structured.

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?

Given no annotations and no output schema, the description is adequate for a simple data-fetching tool with two parameters. It covers the basic purpose and default behavior, but lacks details on output (e.g., what 'esa' means, row format) and error conditions, which could be important for an agent to use it correctly.

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 the schema fully documents both parameters (tableName and limit). The description adds minimal value by mentioning the default limit of 5, but doesn't provide additional context beyond what the schema already covers, such as examples or constraints not in the schema.

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 action ('fetch') and resource ('rows from a specified table'), specifying it's a 'limited sample' with a default of 5 rows. It distinguishes from siblings like 'describe_table' (metadata) or 'run_graphql_query' (full queries), but doesn't explicitly name alternatives.

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?

The description implies usage for previewing table data with a sample, suggesting it's for quick inspection rather than full data retrieval. However, it doesn't explicitly state when to use this versus alternatives like 'run_graphql_query' for complete data or 'list_tables' for table discovery.

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

run_graphql_mutationC

Executes a GraphQL mutation to insert, update, or delete data...

ParametersJSON Schema
NameRequiredDescriptionDefault
mutationYesThe GraphQL mutation string.
variablesNoOptional. An object containing variables...

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool performs data modifications (insert, update, delete), which implies mutation operations, but fails to address critical aspects like authentication requirements, error handling, side effects, or response format. This leaves significant gaps for a tool that modifies data.

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, efficient sentence that directly states the tool's function without unnecessary elaboration. It's appropriately sized for its purpose, though it could be slightly more structured by explicitly contrasting with the query sibling.

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

Completeness2/5

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

Given the complexity of a GraphQL mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or behavioral nuances, making it incomplete for safe and effective use by an AI agent.

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?

The schema description coverage is 100%, so the schema already documents both parameters ('mutation' and 'variables') adequately. The description adds no additional semantic context beyond what's in the schema, such as examples of mutation strings or variable usage, resulting in a baseline score.

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 tool's purpose as executing GraphQL mutations for data operations (insert, update, delete). It specifies the action ('executes') and resource ('GraphQL mutation'), though it doesn't explicitly differentiate from its sibling 'run_graphql_query' beyond the mutation vs query distinction.

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?

The description provides no guidance on when to use this tool versus alternatives like 'run_graphql_query' or other data manipulation tools. It lacks context about prerequisites, appropriate scenarios, or exclusions, leaving the agent to infer usage 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.

run_graphql_queryA

Executes a read-only GraphQL query against the Hasura endpoint...

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe GraphQL query string (must be a read-only operation).
variablesNoOptional. An object containing variables...

TDQS

A3.5/5.0
Behavior3/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. It discloses the 'read-only' behavioral trait, which is crucial for safety, but lacks details on rate limits, authentication needs, error handling, or response format. The description adds some value but doesn't fully compensate for the missing annotations.

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, efficient sentence that front-loads key information ('Executes a read-only GraphQL query'). It wastes no words and clearly communicates the core purpose without unnecessary elaboration.

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?

Given no annotations, no output schema, and a mutation sibling, the description is adequate but has clear gaps. It covers the read-only constraint and endpoint, but doesn't explain return values, error cases, or how it differs from 'run_graphql_mutation'. For a tool with behavioral complexity and sibling tools, more context would be helpful.

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 the schema already documents both parameters thoroughly. The description doesn't add any meaning beyond what's in the schema (e.g., no examples or constraints on query structure). Baseline 3 is appropriate 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 clearly states the verb 'executes' and resource 'GraphQL query' with the specific constraint 'read-only' and target 'Hasura endpoint'. However, it doesn't explicitly distinguish this from its sibling 'run_graphql_mutation', which is a notable gap since both tools involve GraphQL operations against the same endpoint.

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?

The description implies usage through the 'read-only' constraint, suggesting this tool is for queries rather than mutations, but it doesn't explicitly state when to use this vs. 'run_graphql_mutation' or other siblings like 'list_tables'. No explicit alternatives, exclusions, or prerequisites are mentioned.

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. 9 tool updatesv1.0.0
    • First observedaggregate_data
    • First observeddescribe_graphql_type
    • First observeddescribe_table
    • First observedhealth_check
    • First observedlist_root_fields
    • First observedlist_tables
    • First observedpreview_table_data
    • First observedrun_graphql_mutation
    • First observedrun_graphql_query
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

A3.6/5.0

Scored across 9 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no ambiguity. Tools like 'list_tables', 'describe_table', and 'preview_table_data' form a logical progression for table exploration, while 'run_graphql_query' and 'run_graphql_mutation' handle different operation types. The 'aggregate_data' tool provides specific functionality separate from general queries.

Naming Consistency5/5

All tools follow a consistent verb_noun naming pattern throughout. Examples include 'list_tables', 'describe_table', 'run_graphql_query', and 'preview_table_data'. This consistency makes the tool set predictable and easy for agents to understand and navigate.

Tool Count5/5

With 9 tools, this server is well-scoped for its purpose of interacting with Hasura GraphQL. Each tool earns its place by covering distinct aspects like schema exploration, data operations, and system health. The count is neither too sparse nor overwhelming for the domain.

Completeness5/5

The tool surface provides complete coverage for Hasura GraphQL interaction. It includes schema discovery ('list_root_fields', 'describe_graphql_type'), data exploration ('list_tables', 'describe_table', 'preview_table_data'), CRUD operations ('run_graphql_query', 'run_graphql_mutation', 'aggregate_data'), and system monitoring ('health_check'). No obvious gaps exist for core workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-graphql

    launchthatbrand
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.
    758 npm
    3
    MIT

  • PostgreSQL MCP Server

    ahmedmustahid
    A
    license
    Not graded
    quality
    F
    maintenance
    A Model Context Protocol server providing dual transport (HTTP and Stdio) access to PostgreSQL databases, allowing AI assistants to query databases and fetch schema information through natural language.
    49 npm
    31
    MIT

Appeared in Searches