StarRocks MCPサーバーは、AIアシスタントとStarRocksデータベース間の橋渡しとして機能します。クライアント側の複雑な設定を必要とせずに、直接SQL実行、データベース探索、チャートによるデータ可視化、詳細なスキーマ/データ概要の取得が可能になります。
直接 SQL 実行: SELECTクエリ ( read_query ) と DDL/DML コマンド ( write_query ) を実行します。
**データベースの探索:**データベースとテーブルを一覧表示し、テーブル スキーマ ( starrocks://リソース) を取得します。
システム情報: proc://リソース パスを介して StarRocks の内部メトリックと状態にアクセスします。
**詳細な概要:**列の定義、行数、サンプル データなど、テーブル ( table_overview ) またはデータベース全体 ( db_overview ) の包括的な概要を取得します。
**データの視覚化:**クエリを実行し、結果から直接 Plotly チャートを生成します ( query_and_plotly_chart )。
**インテリジェントキャッシュ：**テーブルとデータベースの概要はメモリにキャッシュされ、繰り返しのリクエストを高速化します。必要に応じてキャッシュをバイパスできます。
**柔軟な構成:**環境変数を使用して接続の詳細と動作を設定します。
Related MCP server: starrocks-mcp
MCPサーバーは通常、MCPホストを介して実行されます。StarRocks MCPサーバープロセスの起動方法を指定する設定がホストに渡されます。
インストールされたパッケージでuvを使用する:
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": [
"run",
"--with",
"mcp-server-starrocks",
"mcp-server-starrocks"
],
"env": {
"STARROCKS_HOST": "default localhost",
"STARROCKS_PORT": "default 9030",
"STARROCKS_USER": "default root",
"STARROCKS_PASSWORD": "default empty",
"STARROCKS_DB": "default empty",
"STARROCKS_OVERVIEW_LIMIT": "default 20000"
}
}
}
}ローカルディレクトリでuvを使用する (開発用):
{
"mcpServers": {
"mcp-server-starrocks": {
"command": "uv",
"args": [
"--directory",
"path/to/mcp-server-starrocks", // <-- Update this path
"run",
"mcp-server-starrocks"
],
"env": {
"STARROCKS_HOST": "default localhost",
"STARROCKS_PORT": "default 9030",
"STARROCKS_USER": "default root",
"STARROCKS_PASSWORD": "default empty",
"STARROCKS_DB": "default empty",
"STARROCKS_OVERVIEW_LIMIT": "default 20000"
}
}
}
}環境変数:
STARROCKS_HOST : (オプション) StarRocks FEサービスのホスト名またはIPアドレス。デフォルトはlocalhostです。
STARROCKS_PORT : (オプション) StarRocks FEサービスのMySQLプロトコルポート。デフォルトは9030です。
STARROCKS_USER : (オプション) StarRocks のユーザー名。デフォルトはrootです。
STARROCKS_PASSWORD : (オプション) StarRocksパスワード。デフォルトは空の文字列です。
STARROCKS_DB : (オプション) ツール引数またはリソースURIで指定されていない場合に使用するデフォルトのデータベース。設定されている場合、接続はこのデータベースUSEしようとします。table_overviewやdb_overviewなどのツールはtable_overview引数でデータベース部分が省略されている場合にこのデータベースを使用します。デフォルトは空（デフォルトデータベースなし）です。
STARROCKS_OVERVIEW_LIMIT : (オプション) キャッシュにデータを格納するためにデータを取得する際に、概要ツール ( table_overview 、 db_overview ) によって生成されるテキストの合計文字数のおおよその制限。これは、非常に大きなスキーマや多数のテーブルによる過剰なメモリ使用を防ぐのに役立ちます。デフォルトは20000です。
read_query
説明: SELECT クエリまたは ResultSet を返すその他のコマンド (例: SHOW 、 DESCRIBE ) を実行します。
入力: { "query": "SQL query string" }
**出力:**クエリ結果をCSV形式のテキストコンテンツで出力します。ヘッダー行と行数の概要が含まれます。失敗した場合はエラーメッセージが返されます。
write_query
説明: DDL ( CREATE 、 ALTER 、 DROP )、DML ( INSERT 、 UPDATE 、 DELETE )、または ResultSet を返さないその他の StarRocks コマンドを実行します。
入力: { "query": "SQL command string" }
**出力:**成功を示すテキストコンテンツ（例:「クエリは成功しました。X行が影響を受けました」）またはエラーを報告するテキストコンテンツ。成功した場合、変更は自動的にコミットされます。
query_and_plotly_chart
説明: SQLクエリを実行し、結果をPandas DataFrameに読み込み、指定されたPython式を使用してPlotlyチャートを生成します。サポートUIでの視覚化を目的として設計されています。
入力：
{
"query": "SQL query to fetch data",
"plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'"
}**出力:**次の内容を含むリスト:
TextContent : DataFrame のテキスト表現と、チャートが UI 表示用であることを示す注記。
ImageContent : 生成されたPlotlyチャートはbase64 PNG画像（ image/png ）としてエンコードされます。クエリが失敗した場合、またはクエリでデータが返されなかった場合は、テキストエラーメッセージを返します。
table_overview
**説明:**特定のテーブルの概要を取得します。列数（ DESCRIBEから取得）、行数の合計、サンプル行数（ LIMIT 3 ）。refresh refresh true でない限り、メモリ内キャッシュを使用します。
入力：
{
"table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
"refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
}**出力:**フォーマットされた概要（列数、行数、サンプルデータ）またはエラーメッセージを含むテキストコンテンツ。キャッシュされた結果には、該当する場合、以前のエラーも含まれます。
db_overview
**説明:**指定されたデータベース内のすべてのテーブルの概要（列数、行数、サンプル行）を取得します。refresh refresh true でない限り、各テーブルに対してテーブルレベルのキャッシュを使用します。
入力：
{
"db": "database_name", // Optional if STARROCKS_DB env var is set.
"refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
}**出力:**データベース内にあるすべてのテーブルの概要を連結したテキストコンテンツ。ヘッダーで区切られます。データベースにアクセスできない場合、またはテーブルが含まれていない場合は、エラーメッセージが返されます。
starrocks:///databases
**説明:**構成されたユーザーがアクセスできるすべてのデータベースを一覧表示します。
同等のクエリ: SHOW DATABASES
MIMEタイプ: text/plain
starrocks:///{db}/{table}/schema
**説明:**特定のテーブルのスキーマ定義を取得します。
同等のクエリ: SHOW CREATE TABLE {db}.{table}
MIMEタイプ: text/plain
starrocks:///{db}/tables
**説明:**特定のデータベース内のすべてのテーブルを一覧表示します。
同等のクエリ: SHOW TABLES FROM {db}
MIMEタイプ: text/plain
proc:///{+path}
説明: Linuxの/procと同様に、StarRocksの内部システム情報にアクセスします。 pathパラメータは、必要な情報ノードを指定します。
同等のクエリ: SHOW PROC '/{path}'
MIMEタイプ: text/plain
共通パス:
/frontends - FE ノードに関する情報。
/backends - BE ノードに関する情報 (非クラウド ネイティブ デプロイメントの場合)。
/compute_nodes - CN ノードに関する情報 (クラウド ネイティブ デプロイメント用)。
/dbs - データベースに関する情報。
/dbs/<DB_ID> - ID による特定のデータベースに関する情報。
/dbs/<DB_ID>/<TABLE_ID> - ID による特定のテーブルに関する情報。
/dbs/<DB_ID>/<TABLE_ID>/partitions - テーブルのパーティション情報。
/transactions - データベースごとにグループ化されたトランザクション情報。
/transactions/<DB_ID> - 特定のデータベース ID のトランザクション情報。
/transactions/<DB_ID>/running - データベース ID のトランザクションを実行しています。
/transactions/<DB_ID>/finished - データベース ID の完了したトランザクション。
/jobs - 非同期ジョブ (スキーマ変更、ロールアップなど) に関する情報。
/statistic - 各データベースの統計。
/tasks - エージェントのタスクに関する情報。
/cluster_balance - 負荷分散ステータス情報。
/routine_loads - ルーチン ロード ジョブに関する情報。
/colocation_group - コロケーション参加グループに関する情報。
/catalog - 構成されたカタログ (例: Hive、Iceberg) に関する情報。
このサーバーでは定義されていません。
table_overviewおよびdb_overviewツールは、生成された概要テキストを保存するためにメモリ内キャッシュを利用します。
キャッシュ キーは(database_name, table_name)のタプルです。
table_overviewが呼び出されると、まずキャッシュをチェックします。結果が存在し、 refreshパラメータがfalse （デフォルト）の場合、キャッシュされた結果が直ちに返されます。そうでない場合は、StarRocks からデータを取得し、キャッシュに保存してから返します。
db_overviewが呼び出されると、データベース内のすべてのテーブルが一覧表示され、 table_overviewと同じキャッシュロジック（最初にキャッシュをチェックし、必要に応じてフェッチし、 refreshがfalseまたはキャッシュミスの場合）を使用して各テーブルの概要を取得しようとします。db_overview db_overview``refreshがtrueの場合、そのデータベース内のすべてのテーブルが強制的にリフレッシュされます。
STARROCKS_OVERVIEW_LIMIT環境変数は、キャッシュを作成するときにテーブルごとに生成される概要文字列の最大長のソフト ターゲットを提供し、メモリ使用量の管理に役立ちます。
元のフェッチ中に発生したエラー メッセージを含むキャッシュされた結果は保存され、後続のキャッシュ ヒット時に返されます。
Analyze a query and get analyze result using query profile. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| sql | No | Query SQL | |
| uuid | No | Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 mentions 'using query profile' but does not disclose whether the tool is read-only, requires authentication, has side effects, or what state (e.g., query must be previously executed) is needed. The behavioral traits are minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and includes a concise usage hint. Every sentence adds value without unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the moderate complexity (3 parameters), the description covers the basic purpose and provides a hint about the database parameter. However, it does not clarify the difference between analyzing by SQL vs. UUID, or that the query may need to have been executed first. It is adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing baseline parameter descriptions. The description adds value by explaining that 'set_session_db' can set a per-session default database, indirectly clarifying that the 'db' parameter may be omitted if a default is set. This goes beyond the schema's simple 'database' label.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action ('analyze a query') and the resource ('query'), and mentions using 'query profile', which indicates the tool's specific function. However, the phrasing 'get analyze result' is slightly redundant, and it doesn't clearly distinguish from sibling tools like 'db_summary' or 'read_query'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a hint to use 'set_session_db' for setting a default database, but provides no guidance on when to use this tool versus alternatives (e.g., 'read_query' or 'query_and_plotly_chart'). There is no mention of prerequisites, exclusions, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a query to get it's query dump and profile, output very large, need special tools to do further processing
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | query to execute |
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 that the output is very large and needs special tools, which is useful. However, it does not mention other behavioral traits like destructiveness, permissions, or side effects, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action. It is concise and to the point, though a bit more structure could improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, and no nested objects, the description provides adequate context but does not explain what 'query dump' and 'profile' entail or the return format. It is minimally complete for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions: 'database' and 'query to execute'). The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Run a query to get it's query dump and profile', which clearly identifies the verb (run) and resource (query dump and profile). It also mentions the output is very large, adding context. However, it does not differentiate from sibling tools like 'query_and_plotly_chart' or 'read_query'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by stating 'need special tools to do further processing', suggesting this tool is for large outputs requiring post-processing. However, it does not explicitly state when to use this tool versus alternatives, nor provide conditions to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Quickly get summary of a database with tables' schema and size information. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | Database name. Optional: uses current database by default. | |
| limit | No | Output length limit in characters. Defaults to 10000. Higher values show more tables and details. | |
| refresh | No | Set to true to force refresh, ignoring cache. Defaults to false. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided; the description does not disclose if the tool is read-only, cached, or has side effects. It mentions the refresh parameter but does not explain caching behavior in text, leaving agents without key safety cues.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with an additional useful hint. It is front-loaded and contains no filler, efficiently conveying purpose and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no annotations, the description covers the main use case but falls short on behavioral transparency. The presence of an output schema reduces the need to describe return values. Overall adequate but with gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters. The description adds some value by linking the 'db' parameter to set_session_db, but does not significantly expand on parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a database summary including table schema and size, with a specific verb and resource. It distinguishes from siblings by mentioning set_session_db for default database context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use (quickly get summary) and references set_session_db for setting a default database. However, it does not explicitly state when not to use or compare to siblings like read_query or table_overview.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
using sql query to extract data from database, then using python plotly_expr to generate a chart for UI to display. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | SQL query to execute | |
| format | No | chart output format, json|png|jpeg | jpeg |
| plotly_expr | Yes | a one function call expression, with 2 vars binded: `px` as `import plotly.express as px`, and `df` as dataframe generated by query `plotly_expr` example: `px.scatter(df, x="sepal_width", y="sepal_length", color="species", marginal_y="violin", marginal_x="box", trendline="ols", template="simple_white")` |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It explains the two-step process (query then chart) but does not mention side effects, errors, rate limits, or output format details. The description is simple but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, the first clearly stating the main function. The second sentence provides a related tip but is somewhat tangential. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is fairly complete for a combined query-chart tool. It explains the process and mentions a prerequisite. However, it lacks details on output format or error handling, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, so baseline is 3. The description adds context about the overall workflow but does not elaborate on individual parameters beyond the schema. The mention of set_session_db is peripheral.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it uses SQL query to extract data and then generates a chart with plotly_expr. It distinguishes from siblings like read_query (which only returns data) by explicitly mentioning chart generation. However, it could be more precise by contrasting with other query tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions using set_session_db to set a default database, which is helpful but does not provide guidance on when to use this tool over its siblings (e.g., read_query for data only, analyze_query for analysis). No explicit exclusions or alternatives are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a SELECT query or commands that return a ResultSet. Set output_file to write the full result to disk instead of returning it inline (useful for large results).. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | SQL query to execute | |
| output_file | No | If set, write the full result to this file and return only a summary + small preview inline. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/). Absolute paths (and ~) are used as-is. Format is inferred from the file extension (.csv, .tsv, .json, .jsonl, .ndjson) unless output_format is given. NOTE: the file is written on the server's filesystem, which may not be the client machine in remote/http deployments. | |
| output_format | No | Override file format: csv|tsv|json|jsonl. If omitted, inferred from output_file extension; defaults to csv. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavioral traits. It explains the output_file feature and notes that files are written on the server's filesystem, which is important for remote deployments. However, it does not explicitly state that the tool is read-only or discuss error handling or authentication.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the purpose stated first. It includes two sentences plus a minor note, and every part adds value. The only flaw is an extra period after 'inline'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about the return structure when output_file is not used. It mentions returning 'inline' but does not specify the format or content (e.g., rows, columns). Given there is no output schema, this information is crucial for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value beyond the schema for output_file and output_format, explaining path resolution, environment variables, and format inference. For db, it adds no extra meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Execute a SELECT query or commands that return a ResultSet', which provides a specific verb and resource. It distinguishes this tool from siblings like write_query and analyze_query by focusing on read-only queries that produce a result set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 (e.g., write_query for modifications, analyze_query for explaining). The only instruction is to use set_session_db for default database, which is a side note, not a usage guideline for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set or clear the default database for THIS MCP session. Subsequent tool calls without an explicit db argument will use this database. Pass an empty string or null to clear and fall back to the server's global default. Returns the new effective default for this session.
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | Database name to set as the per-session default. Empty/null clears the override. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It discloses that setting affects subsequent calls without explicit db argument, clarifies clearing behavior, and states the return value. No behavioral contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant words. Every sentence adds critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no annotations, the description is fully complete. It explains purpose, usage, parameter semantics, and return value. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by explaining that empty string or null clears the override, which is not explicitly in the schema. It clarifies the parameter's effect beyond the bare description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sets or clears the default database for the MCP session, using specific verbs ('set', 'clear', 'fall back'). It distinguishes from sibling query tools by focusing on session state management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (set default) and how to clear (empty/null). While it doesn't explicitly state when not to use or list alternatives, the context of sibling tools makes the usage clear. The guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an overview of a specific table: columns, sample rows (up to 3), and total row count. Uses cache unless refresh=true. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name, optionally prefixed with database name (e.g., 'db_name.table_name'). If database is omitted, uses the default database. | |
| refresh | No | Set to true to force refresh, ignoring cache. Defaults to false. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses caching behavior and refresh option, which is important for understanding tool behavior. No destructive actions are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no fluff. First sentence clearly states the tool's action and output, second provides important context about caching and database setup. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (2 params, output schema exists), the description covers key aspects: output components, caching, default database. Minor omission like error behavior or limit on sample rows is compensated by output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description does not add semantic meaning beyond the schema descriptions. The parameter details are fully covered by the schema, so description adds no extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides an overview of a table including columns, sample rows, and row count. However, it does not explicitly differentiate from sibling tools like read_query or analyze_query, which are for querying rather than generating a summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on caching and default database setup via set_session_db, but lacks explicit guidance on when to use this tool versus alternatives (e.g., read_query for raw data).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a DDL/DML or other StarRocks command that do not have a ResultSet. Use set_session_db to set a per-session default database
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | database | |
| query | Yes | SQL to execute |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers non-ResultSet nature but lacks details on side effects, permissions, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with core purpose, no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output schema; description doesn't specify return format or error handling, but purpose and parameters are adequately covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters; description adds value by suggesting set_session_db for default database, enhancing understanding of db parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it executes DDL/DML commands without ResultSet, distinguishing it from sibling tools like read_query which returns results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions using set_session_db for default database but does not explicitly state when to use vs alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.4.0read_query2 fields changedInput schema / properties / output_fileAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "If set, write the full result to this file and return only a summary + small preview inline. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/). Absolute paths (and ~) are used as-is. Format is inferred from the file extension (.csv, .tsv, .json, .jsonl, .ndjson) unless output_format is given. NOTE: the file is written on the server's filesystem, which may not be the client machine in remote/http deployments."
+}Input schema / properties / output_formatAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Override file format: csv|tsv|json|jsonl. If omitted, inferred from output_file extension; defaults to csv."
+}set_session_dbv0.3.0analyze_query12 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dbAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "database"
+}Input schema / properties / sql / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / sql / defaultAdded value: +nullInput schema / properties / sql / titleRemoved value: -"Sql"Input schema / properties / sql / typeRemoved value: -"string"Input schema / properties / uuid / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / uuid / defaultAdded value: +nullInput schema / properties / uuid / titleRemoved value: -"Uuid"Input schema / properties / uuid / typeRemoved value: -"string"Input schema / requiredRemoved value: -[
- "uuid",
- "sql"
-]Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object",
+ "x-fastmcp-wrap-result": true
+}collect_query_dump_and_profiledb_overviewdb_summaryquery_and_plotly_chart5 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dbAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "database"
+}Input schema / properties / formatAdded value: +{
+ "default": "jpeg",
+ "description": "chart output format, json|png|jpeg",
+ "type": "string"
+}Input schema / properties / plotly_expr / titleRemoved value: -"Plotly Expr"Input schema / properties / query / titleRemoved value: -"Query"read_query3 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dbAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "database"
+}Input schema / properties / query / titleRemoved value: -"Query"table_overview4 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / refresh / titleRemoved value: -"Refresh"Input schema / properties / table / titleRemoved value: -"Table"Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "result": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "result"
+ ],
+ "type": "object",
+ "x-fastmcp-wrap-result": true
+}write_query3 fields changedInput schema / additionalPropertiesAdded value: +falseInput schema / properties / dbAdded value: +{
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "database"
+}Input schema / properties / query / titleRemoved value: -"Query"v1.0.0analyze_querydb_overviewquery_and_plotly_chartread_querytable_overviewwrite_queryScored across 8 tools
Each tool targets a distinct function: query execution, analysis, chart generation, schema summary, etc. There is slight overlap between read_query and query_and_plotly_chart, but their outputs differ (raw data vs chart), and descriptions clarify the distinction. No major confusion.
Tool names follow no consistent pattern: some are verb_noun (e.g., read_query), some are noun_verb (e.g., db_summary), some include conjunctions (query_and_plotly_chart), and verbs vary (analyze, collect, set, write). This inconsistency may confuse an agent trying to infer tool purposes from naming.
With 8 tools, the server is well-scoped for a database MCP server covering querying, analysis, schema browsing, and charting. Each tool serves a clear purpose without being excessive or minimal.
The tool set covers core database interactions: query (read and write), analysis, schema overview, and charting. A minor gap is the absence of a tool to list all databases, but db_summary and set_session_db partially address this. Overall, the surface is reasonably complete for the stated purpose.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
