このプロジェクトは、AI エージェント (Cursor、Claude Desktop など) がテーブルの一覧表示やスキーマの検査など、複数の PostgreSQL データベースと対話できるように設計された、非常に高速で型安全、かつフル機能のモデル コンテキスト プロトコル (MCP) サーバーを実装します。
これは、Bun、TypeScript、 postgresを使用して構築されており、堅牢な MCP サーバーを構築するためのfastmcpフレームワークの高度な機能を活用しています。
これはコードにインポートするライブラリではありません。スタンドアロンのサーバーアプリケーションです。プロセスとして実行され、MCPクライアント（AIエージェントなど）はJSONベースのモデルコンテキストプロトコル（v2.0）を使用してサーバーアプリケーションと通信します。通常は、クライアントアプリケーション（例：Cursor）が管理するstdio接続を介して通信します。
Related MCP server: Postgres MCP Pro
パッケージには、MCP サーバーを直接テストするための組み込み CLI コマンドが含まれています。
# From the project repository:
bun run cli
# This will start an interactive MCP CLI session where you can:
# - Call any of the PostgreSQL tools (query_tool, execute_tool, etc.)
# - View server capabilities
# - Test queries against your configured databasesMCP インスペクターを使用して視覚的にテストおよびデバッグすることもできます。
# From the project repository:
bun run inspectbunx postgres-mcp実行中にこのエラーが表示された場合:
FastPostgresMCP started
[warning] FastMCP could not infer client capabilitiesping メッセージが続く場合は、次のことを意味します。
MCPサーバーが正常に起動しました
クライアントは正常に接続しました
しかし、クライアントはpingリクエストを送信するだけで、適切に機能のネゴシエーションを行っていません。
これは通常、適切なMCPクライアントを使用する必要があることを示しています。以下をお試しください。
bun run cliを使用して MCP CLI でテストする
インストールセクションの説明に従って、Cursor または Claude Desktop で MCP サーバーを構成する
カスタム MCP クライアントを開発している場合は、機能ネゴシエーションを含む MCP プロトコルが適切に実装されていることを確認してください。
🚀 超高速: Bun とfastmcp上に構築されています。
🔒 タイプセーフ: Zod スキーマ検証を備えたエンドツーエンドの TypeScript。
🐘 マルチデータベースのサポート: .envで定義された複数の PostgreSQL インスタンスに接続し、それらのインスタンス間のやり取りを管理します。
🛡️ 設計によるセキュリティ: postgres経由のパラメーター化されたクエリにより、SQL インジェクションを防止します。
🔑 オプションの認証: API キー検証 ( fastmcpのauthenticateフック) を使用して、ネットワークベースの接続 (SSE/HTTP) を保護します。
📄 MCP リソース経由のデータベース スキーマ:
テーブルの一覧: db://{dbAlias}/schema/tablesを介してデータベース内のテーブルの一覧を取得します。
テーブル スキーマの検査: db://{dbAlias}/schema/{tableName}を介して特定のテーブルの詳細な列情報を取得します。
💬 強化されたツールインタラクション:
**ツール内ログ:**ツールは詳細なログをクライアントに送り返します ( logコンテキスト)。
**進行状況レポート:**長時間実行される操作は進行状況を報告します ( reportProgressコンテキスト)。
**🧠 セッション対応:**ツール実行コンテキスト ( sessionコンテキスト) 内のセッション情報にアクセスします。
**📡 イベント駆動型:**接続/セッション イベントの処理にserver.onとsession.onを使用します。
**🔧 最新の開発者エクスペリエンス (DX):**明確な構成、直感的な API、 fastmcpツールによる簡単なテスト。
FastMCPサーバーコア
server.addTool ( query_tool 、 execute_tool 、 schema_tool 、 transaction_toolの場合)
server.addResourceTemplate (テーブルの一覧表示とテーブルスキーマの検査用)
server.start ( stdioに重点を置き、 sse / httpに適応可能)
オプション: authenticateフック (API キー検証用)
ツール実行context ( log 、 reportProgress 、 session )
パラメータスキーマ検証のためのZod
server.on (接続ログ用)
（潜在的に）セッション固有のロジックのためのsession.on
**Bun (v1.0 以降を推奨):**インストールされ、PATH に含まれています。
**PostgreSQL データベース:**アクセス資格情報と接続。ユーザーにはinformation_schemaをクエリする権限が必要です。
# Install globally
npm install -g postgres-mcp
# Or install locally in your project
npm install postgres-mcpnpm パッケージはhttps://www.npmjs.com/package/postgres-mcpから入手できます。
リポジトリをクローンします。
# Replace with your actual repository URL
git clone https://github.com/llm-graph/postgres-mcp.git
cd postgres-mcp依存関係をインストールします:
bun install適切な.envファイルから読み込まれた環境変数を使用して構成します。
環境ファイルを作成します。
本番環境の場合: cp .env.example .env
開発の場合: cp .env.development.example .env.development
**環境ファイルの読み込み順序:**サーバーは、次の優先順位でファイルから環境変数を読み込みます。
.env.<NODE_ENV> (例: .env.development 、 .env.production 、 .env.staging )
.env.local (バージョン管理されていないローカルオーバーライド用)
.env (デフォルトのフォールバック) これにより、環境ごとに異なる構成が可能になります。
環境ファイルを編集して、データベース接続と認証を定義します。
DB_ALIASES - 一意のDBエイリアスのカンマ区切りリスト
DEFAULT_DB_ALIAS - ツール呼び出しで 'dbAlias' が省略された場合のデフォルトのエイリアス
各エイリアスのデータベース接続の詳細（例： DB_MAIN_HOST 、 DB_REPORTING_HOST ）
オプションのAPIキー認証（ ENABLE_AUTH 、 MCP_API_KEY ）
# Example .env file - Key Variables
# REQUIRED: Comma-separated list of unique DB aliases
DB_ALIASES=main,reporting
# REQUIRED: Default alias if 'dbAlias' is omitted in tool calls
DEFAULT_DB_ALIAS=main
# OPTIONAL: Enable API Key auth (primarily for network transports)
ENABLE_AUTH=false
MCP_API_KEY=your_super_secret_api_key_here # CHANGE THIS
# Define DB connection details for each alias (DB_MAIN_*, DB_REPORTING_*, etc.)
DB_MAIN_HOST=localhost
DB_MAIN_PORT=5432
DB_MAIN_NAME=app_prod_db
DB_MAIN_USER=app_user
DB_MAIN_PASSWORD=app_secret_password
DB_MAIN_SSL=disable
# Alternative: Use connection URLs
# DB_MAIN_URL=postgres://user:password@localhost:5432/database?sslmode=require
# --- Optional: Server Logging Level ---
# LOG_LEVEL=info # debug, info, warn, error (defaults to info)Bunを使用してこのサーバーを直接実行します。通常、AIクライアント（Cursorなど）がこのコマンドの起動と管理を行います。
手動で実行するには: postgres-mcp
プロジェクトから実行するには: npx postgres-mcp
またはプログラムでインポートします:
// server.js
import { startServer } from 'postgres-mcp';
// Start the MCP server
startServer();手動で実行するには（テスト用）： bun run src/index.ts
手動開発モード: bun run --watch src/index.ts
fastmcp CLIツールを使ったテスト対話型ターミナル: bunx fastmcp dev src/index.ts
Web UI インスペクター: bunx fastmcp inspect src/index.ts
postgres-mcp は、スタンドアロンの MCP サーバーとして実行するだけでなく、Node.js/TypeScript アプリケーション内のライブラリとしてプログラム的に使用することもできます。
import { createPostgresMcp } from 'postgres-mcp';
// Create the PostgresMcp instance
const postgresMcp = createPostgresMcp();
// Start the server
postgresMcp.start();
// Direct database operations
const results = await postgresMcp.executeQuery(
'SELECT * FROM users WHERE role = $1',
['admin'],
'main' // optional database alias
);
// When done, stop the server and close connections
await postgresMcp.stop();より単純なユースケースでは、特定の関数を直接インポートできます。
import {
initConnections,
closeConnections,
executeQuery,
executeCommand,
executeTransaction,
getTableSchema,
getAllTableSchemas
} from 'postgres-mcp';
// Configure database connections
const dbConfigs = {
main: {
host: 'localhost',
port: 5432,
database: 'my_db',
user: 'db_user',
password: 'db_password'
}
};
// Initialize connections
initConnections(dbConfigs);
// Execute a query
const results = await executeQuery(
'SELECT * FROM users WHERE role = $1',
['admin'],
'main'
);
// Get schema for a single table
const schema = await getTableSchema('users', 'main');
// Get schema for all tables in the database
const allSchemas = await getAllTableSchemas('main');
// Close connections when done
await closeConnections();const postgresMcp = createPostgresMcp({
// Custom database configurations (override .env)
databaseConfigs: {
main: {
host: 'localhost',
port: 5432,
database: 'app_db',
user: 'app_user',
password: 'password',
ssl: 'disable'
}
},
// Server configuration
serverConfig: {
name: 'Custom PostgresMCP',
defaultDbAlias: 'main'
},
// Transport options: 'stdio', 'sse', or 'http'
transport: 'http',
port: 3456
});プログラム API の完全なドキュメントについては、 docs/programmatic-api.mdを参照してください。
AI エージェント (MCP クライアント) を構成して、コマンド/引数メカニズムを介してこのサーバー スクリプトを実行します。
カーソル設定/環境設定を開きます (Cmd+, または Ctrl+,)。
「拡張機能」->「MCP」に移動します。
「MCP サーバーの追加」をクリックするか、 settings.jsonを編集します。
次の JSON 構成を追加します。
// In Cursor's settings.json or MCP configuration UI
{
"mcpServers": {
"postgres-mcp": { // Unique name for Cursor
"description": "MCP Server for PostgreSQL DBs (Main, Reporting)",
"command": "bunx", // Use 'bun' or provide absolute path: "/Users/your_username/.bun/bin/bun"
"args": [
"postgres-mcp"
// or
// *** ABSOLUTE PATH to your server's entry point ***
// "/Users/your_username/projects/postgres-mcp/src/index.ts" /
],
"env": {
// .env file in project dir is loaded automatically by Bun.
// Add overrides or Cursor-specific vars here if needed.
},
"enabled": true
}
}
}カーソル を保存して再起動するか、「MCP サーバーを再ロード」します。
カーソルの MCP ステータス/ログで接続を確認します。
config.jsonを見つけて編集します (パスについては前の README を参照してください)。
argsの絶対パスを使用して、 mcpServersの下に同様のエントリを追加します。
Claude Desktop を再起動します。
ENABLE_AUTH=trueの場合、 MCP_API_KEYに一致するX-API-Keyヘッダーを介してネットワーク トランスポート (HTTP/SSE) を保護します。
stdio接続 (Cursor/Claude のデフォルト) は通常、このチェックをバイパスします。
URI テンプレート: db://{dbAlias}/schema/tables
**説明:**指定されたデータベースエイリアス (通常は「public」スキーマ) 内のユーザー テーブル名のリストを取得します。
リソース定義 ( addResourceTemplate ):
uriTemplate : "db://{dbAlias}/schema/tables"
arguments :
dbAlias : (文字列、必須) - データベースのエイリアス ( .envから)。
load({ dbAlias }) : データベースに接続し、 information_schema.tables (パブリック スキーマの基本テーブルに対してフィルター処理され、実装でカスタマイズ可能) をクエリし、結果を JSON 文字列配列["table1", "table2", ...]としてフォーマットし、 { text: "..." }を返します。
使用例 (AI プロンプト): 「リソースdb://main/schema/tablesを取得して、メイン データベース内のテーブルを一覧表示します。」
URI テンプレート: db://{dbAlias}/schema/{tableName}
**説明:**特定のテーブルの詳細なスキーマ情報 (列、タイプ、NULL 値可能性、デフォルト) を提供します。
リソース定義 ( addResourceTemplate ):
uriTemplate : "db://{dbAlias}/schema/{tableName}"
arguments :
dbAlias : (文字列、必須) - データベースの別名。
tableName : (文字列、必須) - テーブルの名前。
load({ dbAlias, tableName }) : 接続し、特定のテーブルのinformation_schema.columnsを照会し、列オブジェクトの JSON 文字列配列としてフォーマットし、 { text: "..." }を返します。
使用例 (AI プロンプト): 「リソースdb://reporting/schema/daily_salesについて説明してください。」
応答コンテンツの例 (JSON 文字列):
"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"ツールはcontextオブジェクト ( log 、 reportProgress 、 session ) を受け取ります。
query_tool読み取り専用の SQL クエリを実行します。
**説明:**読み取り専用 SQL を安全に実行し、実行ログ/進行状況とともに結果を取得します。
パラメーター: statement (文字列)、 params (配列、opt)、 dbAlias (文字列、opt)。
コンテキストの使用法: log.info/debug 、オプションのreportProgress 、アクセスsession 。
**戻り値:**行配列の JSON 文字列。
リクエスト例:
{
"tool_name": "query_tool",
"arguments": {
"statement": "SELECT product_id, name, price FROM products WHERE category = $1 AND price < $2 ORDER BY name LIMIT 10",
"params": ["electronics", 500],
"dbAlias": "main"
}
}応答コンテンツの例 (JSON 文字列):
"[{\"product_id\":123,\"name\":\"Example Gadget\",\"price\":499.99},{\"product_id\":456,\"name\":\"Another Device\",\"price\":350.00}]"execute_toolデータを変更する SQL ステートメントを実行します。
**説明:**実行ログを使用して、データを変更する SQL を安全に実行します。
パラメーター: statement (文字列)、 params (配列、opt)、 dbAlias (文字列、opt)。
コンテキストの使用法: log.info/debug 、アクセスsession 。
**戻り値:**影響を受ける行を示す文字列。
リクエスト例:
{
"tool_name": "execute_tool",
"arguments": {
"statement": "UPDATE users SET last_login = NOW() WHERE user_id = $1",
"params": [54321]
// dbAlias omitted, uses DEFAULT_DB_ALIAS
}
}応答内容の例（文字列）:
"Rows affected: 1"schema_tool特定のテーブルの詳細なスキーマ情報を取得します。
**説明:**データベース テーブルの列の定義と詳細を取得します。
パラメータ: tableName (文字列)、 dbAlias (文字列、opt)。
コンテキストの使用法: log.info 、アクセスsession 。
**戻り値:**列情報オブジェクトの JSON 文字列配列。
リクエスト例:
{
"tool_name": "schema_tool",
"arguments": {
"tableName": "user_sessions",
"dbAlias": "main"
}
}応答コンテンツの例 (JSON 文字列):
"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"transaction_tool複数の SQL ステートメントをアトミックに実行します。
**説明:**ステップのログ記録/進行状況とともに、トランザクション内で SQL シーケンスを実行します。
パラメーター: operations ({statement, params} の配列)、 dbAlias (文字列、opt)。
コンテキストの使用reportProgress: log.info/debug/error``session 。
**戻り値:**成功/失敗をまとめた JSON 文字列: {"success": true, "results": [...]}または{"success": false, "error": ..., "failedOperationIndex": ...} 。
リクエスト例:
{
"tool_name": "transaction_tool",
"arguments": {
"operations": [
{
"statement": "INSERT INTO orders (customer_id, order_date, status) VALUES ($1, NOW(), 'pending') RETURNING order_id",
"params": [101]
},
{
"statement": "INSERT INTO order_items (order_id, product_sku, quantity, price) VALUES ($1, $2, $3, $4)",
"params": [9999, "GADGET-X", 2, 49.99]
},
{
"statement": "UPDATE inventory SET stock_count = stock_count - $1 WHERE product_sku = $2 AND stock_count >= $1",
"params": [2, "GADGET-X"]
}
],
"dbAlias": "main"
}
}成功応答コンテンツの例 (JSON 文字列):
"{\"success\":true,\"results\":[{\"operation\":0,\"rowsAffected\":1},{\"operation\":1,\"rowsAffected\":1},{\"operation\":2,\"rowsAffected\":1}]}"エラー応答コンテンツの例 (JSON 文字列):
"{\"success\":false,\"error\":\"Error executing operation 2: new row for relation \\\"inventory\\\" violates check constraint \\\"stock_count_non_negative\\\"\",\"failedOperationIndex\":2}"クライアント接続のログを記録するためにserver.on('connect'/'disconnect')を使用します。
必要に応じて、より詳細なセッション イベント処理のためにsession.on(...)を使用できます。
**SQLインジェクション:**パラメータ化されたクエリによって軽減されます。直接入力の連結は行われません。
データベース権限: **重要。**各DB_<ALIAS>_USERに、スキーマ/テーブル一覧リソースのinformation_schemaへの読み取りアクセスを含む最小限の権限を割り当てます。
SSL/TLS:本番環境では必須( DB_<ALIAS>_SSL=requireまたはより厳密)。
シークレット管理： .envファイルを保護します（ .gitignoreに追加します）。本番環境では、安全なシークレット管理（Vault、Doppler、クラウドシークレット）を使用します。
認証スコープ: authenticateフックは主にネットワーク トランスポートを保護します。stdio stdioは実行環境に依存します。
**データの機密性:**接続/ツールを介してアクセスできるデータに注意してください。
**リソースクエリ：**テーブル（ information_schema.tables ）とスキーマ（ information_schema.columns ）の一覧表示に使用されるクエリは、一般的に安全ですが、データベース権限に依存します。設定されたユーザーに適切な読み取りアクセス権があることを確認してください。セキュリティや明確さの観点から、必要に応じてテーブル一覧表示クエリ（例：スキーマフィルタリング）をカスタマイズしてください。
このプロジェクトはMITライセンスに基づいてライセンスされています。詳細はLICENSEファイルをご覧ください。
初回リリース
PostgreSQL 用のフル機能 MCP サーバー
複数のデータベース接続のサポート
クエリ、実行、スキーマ検査、トランザクションのためのツール
スキーマイントロスペクションのリソース
包括的なドキュメントと例
Safely execute a data-modifying SQL statement
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| dbAlias | No | ||
| statement | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Uses the word 'Safely' but does not elaborate on safety mechanisms, error handling, or any behavioral traits. No annotations provided to compensate.
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, adequately concise but too brief to provide useful information beyond the name.
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?
With no output schema, no annotations, and 3 undocumented parameters, the description is incomplete for an SQL execution tool. Does not explain return values or parameter 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?
The description does not mention any parameters despite 0% schema coverage. No explanation of 'params', 'dbAlias', or 'statement' 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?
Clearly states 'Safely execute a data-modifying SQL statement', specifying verb (execute) and resource (SQL statement), and distinguishes from read-only query_tool and schema_tool.
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 guidance on when to use vs. sibling tools (query_tool, schema_tool, transaction_tool). Does not mention when not to use or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Safely execute a read-only SQL query and retrieve results
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| dbAlias | No | ||
| statement | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose all behavioral traits. It only mentions 'safely' and 'read-only', but fails to cover error handling, authentication requirements, result format, rate limits, or side effects. The minimal disclosure leaves significant uncertainty about tool 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?
The description is a single sentence, which is concise but at the expense of necessary details. It is front-loaded with the purpose but omits parameter explanations and usage context. Every sentence should earn its place; this one only partially does.
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 complexity (3 parameters, no schema descriptions, no annotations, no output schema, and sibling tools), the description is incomplete. It fails to document how to use parameters, the output format, or how this tool relates to siblings. Significant gaps remain for the agent to function correctly.
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 0%, and the description provides no details about the three parameters (statement, params, dbAlias). It does not explain what params does, how to format the statement, or the role of dbAlias. The description adds zero semantic value beyond the raw 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's purpose: 'Safely execute a read-only SQL query and retrieve results'. It specifies a verb ('execute'), a resource ('SQL query'), and a key constraint ('read-only'), effectively distinguishing it from sibling tools like execute_tool (likely for writes) and transaction_tool (for transactional operations).
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 for read-only queries via the 'read-only' qualifier, but does not explicitly state when to use this tool versus alternatives like execute_tool for writes or transaction_tool for transactions. No when-not guidance or alternative names are provided, leaving the agent to infer usage from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve detailed schema information for a specific table
| Name | Required | Description | Default |
|---|---|---|---|
| dbAlias | No | ||
| tableName | 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 only states it retrieves schema info but does not disclose read-only nature, error handling, or authentication requirements.
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 key action, but lacks necessary detail. It is minimally concise at the expense of completeness.
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, no annotations, and 2 under-documented parameters, the description is severely incomplete. It does not explain what 'detailed schema information' entails or how to use the optional dbAlias.
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 0%, yet the description does not explain the parameters (dbAlias, tableName) beyond the bare schema. The description fails to add meaning, e.g., the role of dbAlias or format of tableName.
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 verb 'retrieve' and the resource 'detailed schema information for a specific table'. However, it does not differentiate from sibling tools like query_tool, which might also retrieve schema-related data.
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 guidance is given on when to use this tool versus alternatives such as execute_tool or query_tool. The description does not mention prerequisites or exclusionary conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute multiple SQL statements as a single atomic transaction
| Name | Required | Description | Default |
|---|---|---|---|
| dbAlias | No | ||
| operations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. 'Atomic transaction' implies ACID properties, but doesn't disclose rollback behavior, error handling, timeouts, or constraints. Adequate but not detailed.
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, no wasted words. Efficiently conveys core functionality.
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?
No output schema, no annotations, and sibling tools suggest similar operations. Description lacks details on return values, error handling, transaction lifecycle, or limitations. Incomplete for a multi-statement 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 0%, meaning description adds no information about parameters like dbAlias or operations. The term 'multiple SQL statements' loosely maps to operations array but does not explain structure, required fields, or defaults.
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 executes multiple SQL statements atomically, which is a specific verb+resource. It distinguishes from siblings like execute_tool (likely single statement) and query_tool (read-only) by emphasizing atomic multi-statement execution.
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 guidance on when to use this tool versus alternatives like execute_tool or query_tool. Description does not mention use cases, prerequisites, 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.
v1.0.0execute_toolquery_toolschema_tooltransaction_toolScored across 4 tools
Each tool has a well-defined and distinct purpose: execute_tool for data modification, query_tool for read-only queries, schema_tool for table metadata, and transaction_tool for atomic operations. There is no ambiguity or overlap.
All tool names follow a consistent verb_tool pattern using snake_case (execute_tool, query_tool, schema_tool, transaction_tool). The naming is predictable and clear.
With four tools, the set is minimal but covers essential database operations (read, write, schema, transactions). While missing some auxiliary functions like listing tables, the count is appropriate for a focused server.
The tools cover the main CRUD lifecycle (via query and execute) and add schema retrieval and transactions. Minor gaps exist, such as lacking a tool to list all tables, but the core workflows are supported.
Xata MCP server lets AI agents interact with your Xata projects, and Postgres database branches.
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.