What can you do with this server?

This server is a read-only MCP gateway to SQL databases that lets LLMs safely inspect and query data, then export or document results. * Query databases (MSSQL, PostgreSQL, MySQL) using only SELECT statements, with automatic validation and row caps. * List available databases and set/select a default database per call. * List tables and describe table schemas (columns, indexes, keys, constraints, size/row stats). * Explain a SELECT query without executing it (returns the database's estimated execution plan). * Export query results to CSV or JSON files, streaming large datasets without row limits. * Save query SQL and results as a Markdown report for test evidence. * Paginate query results via skip/take (up to 100 rows per call) and get total row counts. * Use caching, configurable timeouts, and database allow-lists (exact names or regex) for secure access.

Which integrations are available for this server?

Enables read-only SQL database access to MySQL databases, supporting SELECT queries, table listing, schema description, query explanation, and export of results to CSV/JSON/Markdown. Enables read-only SQL database access to PostgreSQL databases, supporting SELECT queries, table listing, schema description, query explanation, and export of results to CSV/JSON/Markdown.

How do I use sqldb-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@sqldb-mcp-server show me the first 10 users" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

sqldb-mcp-server

by akrym1582

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

@akrym1582/sqldb-mcp-server

A read-only Model Context Protocol (MCP) server that exposes SQL database access to LLMs.

Features

Multi-database – supports MSSQL, PostgreSQL, and MySQL
Read-only – only SELECT statements are allowed (enforced via AST-level SQL parsing with the correct dialect per DB type)
LLM-optimised – results use a compact columnar format (column list + value rows) to reduce token usage
Pagination – skip / take parameters with automatic cap at 100 rows
Total-count aware – every query result includes meta.totalCount so the LLM knows how many rows exist
Caching – query / schema results are cached with a configurable TTL
File export – stream query results to CSV or JSON files without a row-count limit
Markdown evidence export – save SQL and query results as a Markdown report file for test evidence
Database selection – allow exact database names and regular-expression matches, then select a database per tool call
Seven MCP tools: listDatabases, query, listTables, describeTable, explainQuery, exportQuery, saveQueryEvidence

Related MCP server: sqlite-mcp-server

Installation

From npm (recommended)

# Install globally
npm install -g @akrym1582/sqldb-mcp-server

# Or run directly with npx (no install needed)
npx @akrym1582/sqldb-mcp-server

From source

git clone https://github.com/akrym1582/sqldb-mcp-server.git
cd sqldb-mcp-server
npm install
npm run build

Quick Start

# 1. Install globally
npm install -g @akrym1582/sqldb-mcp-server

# 2. Configure environment variables (see below)
export DB_TYPE=postgresql
export DB_HOST=localhost
export DB_USER=myuser
export DB_PASSWORD=mypassword
export DB_NAME=mydb

# 3. Run
sqldb-mcp-server

Or use in your MCP client configuration (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "sqldb": {
      "command": "npx",
      "args": ["-y", "@akrym1582/sqldb-mcp-server"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "myuser",
        "DB_PASSWORD": "mypassword",
        "DB_NAME": "mydb"
      }
    }
  }
}

Environment Variables

Variable	Default	Description
`DB_TYPE`	`mssql`	Database type: `mssql`, `postgresql`, or `mysql`
`DB_HOST`	–	Database server hostname
`DB_PORT`	`1433` / `5432` / `3306`	Database server port (default depends on `DB_TYPE`)
`DB_USER`	–	Database username
`DB_PASSWORD`	–	Database password
`DB_NAME`	–	Allowed databases: comma-separated exact names and/or JavaScript regex literals (for example `app,analytics,/^tenant_[0-9]+$/`)
`DB_DEFAULT`	first allowed database	Default database when a tool call omits `database`; it must be allowed by `DB_NAME`
`DB_ENCRYPT`	`true` for MSSQL/PostgreSQL, `false` for MySQL	Enables encrypted DB connections. MSSQL trusts the server certificate. PostgreSQL tries SSL first and falls back to plain if SSL is unavailable. MySQL uses TLS with certificate verification disabled when enabled.
`DB_QUERY_TIMEOUT`	`30000`	Query timeout in milliseconds (used by `query` / `explainQuery`)
`EXPORT_QUERY_TIMEOUT`	`300000`	Export query timeout in milliseconds (used by `exportQuery`; default 5 min)
`CACHE_TTL`	`60`	Cache TTL in seconds

Default ports by DB type

`DB_TYPE`	Default `DB_PORT`
`mssql`	`1433`
`postgresql`	`5432`
`mysql`	`3306`

MCP Tools

Every database-aware tool accepts an optional database string. If omitted, DB_DEFAULT is used, or otherwise the first exact/matched database in DB_NAME. A requested database must match the configured allow-list; arbitrary database access is rejected.

Regular-expression entries are resolved against databases visible to the configured user. When using regex-only PostgreSQL configuration, ensure the user has a connectable maintenance database (normally the database with the same name as the user); MSSQL and MySQL can enumerate databases without selecting one.

`listDatabases`

List the databases available to the MCP tools and identify the current default:

[
  { "name": "app", "isDefault": true },
  { "name": "tenant_42", "isDefault": false }
]

`query`

Execute a SELECT SQL statement.

{
  "sql": "SELECT id, name FROM users WHERE active = 1",
  "database": "app",
  "skip": 0,
  "take": 10
}

Response format (compact / token-efficient):

{
  "meta": { "totalCount": 42, "returnedCount": 10, "skip": 0, "take": 10 },
  "columns": ["id", "name"],
  "rows": [[1, "Alice"], [2, "Bob"], ...]
}

`listTables`

List all base tables in a selected database. Pass { "database": "app" }, or omit it to use the default.

[{ "schema": "dbo", "name": "users" }, ...]

`describeTable`

Describe a table's columns, indexes, foreign keys, check constraints, and size statistics.

{ "database": "app", "table": "dbo.users" }

`explainQuery`

Return the estimated execution plan for a SELECT query without executing it.

{ "database": "app", "sql": "SELECT * FROM orders WHERE status = 'open'" }

`exportQuery`

Stream a SELECT query result to a file. Designed for large datasets – there is no row-count limit and results are written directly to disk using Node.js streams.

{
  "sql": "SELECT * FROM large_table",
  "database": "analytics",
  "filepath": "/tmp/export.csv",
  "format": "csv",
  "options": { "delimiter": ",", "bom": false }
}

format defaults to "csv" if omitted. "json" is also supported.

CSV options (all optional):

Option	Default	Description
`delimiter`	`","`	Column separator
`nullValue`	`""`	String to write for `NULL` / `undefined` cells
`bom`	`false`	Prepend UTF-8 BOM (useful for Excel)

JSON options (all optional):

Option	Default	Description
`pretty`	`false`	Indent the output JSON

Response format:

{
  "filepath": "/tmp/export.csv",
  "format": "csv",
  "rowCount": 50000
}

The tool uses a separate, longer-lived connection pool whose requestTimeout is controlled by EXPORT_QUERY_TIMEOUT (default 300 000 ms = 5 min). Increase this value for very large exports.

`saveQueryEvidence`

Execute a SELECT query and save the SQL plus the returned rows as a Markdown report file for test evidence.

{
  "sql": "SELECT id, name FROM users LIMIT 10",
  "database": "app",
  "filepath": "/tmp/query-evidence.md"
}

Response format:

{
  "filepath": "/tmp/query-evidence.md",
  "rowCount": 10,
  "previewRows": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

If an error occurs, the tool returns the error message text instead of a success payload.

Development

# Clone the repository
git clone https://github.com/akrym1582/sqldb-mcp-server.git
cd sqldb-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your DB credentials

# Run in dev mode (no compile step)
npm run dev

# Or build and run
npm run build
npm start

# Run unit tests
npm test

Project Structure

src/
  mcp/
    server.ts           # MCP server entry point
    tools/
      query.ts          # query tool
      listTables.ts     # listTables tool
      describeTable.ts  # describeTable tool
      explainQuery.ts   # explainQuery tool
      exportQuery.ts    # exportQuery tool (streaming file export)
  db/
    index.ts            # DB adapter factory (selects adapter from DB_TYPE)
    types.ts            # DB interfaces (including queryStream)
    adapters/
      mssql.ts          # Microsoft SQL Server implementation
      postgresql.ts     # PostgreSQL implementation (pg + pg-cursor)
      mysql.ts          # MySQL implementation (mysql2)
  utils/
    row-result.ts       # Compact columnar result format
    sanitize.ts         # AST-based SQL read-only validation (dialect-aware)
    pagination.ts       # skip/take normalisation
    cache.ts            # TTL in-memory cache
    export-writer.ts    # Streaming CSV / JSON file writer
  __tests__/            # Unit tests

Available Tools

7 tools

describeTableA

Describe a table: returns columns (name, type, nullability, primary key, identity), indexes, foreign keys, check constraints, and table-level size/row-count statistics.

ParametersJSON Schema

Name	Required	Description	Default
`table`	Yes	Table name to describe. Optionally prefix with schema: 'schema.table'
`database`	No	Database containing the table; omit to use the default

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description carries the behavioral disclosure burden. It states exactly what is returned and 'Describe' strongly implies a read-only metadata operation, but it does not explicitly confirm that no data is modified, nor does it mention permission, error, or performance behavior. This is adequate but leaves the safety profile implicit.

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 well-structured sentence with a front-loaded purpose and a concise list of return categories. It contains no redundant wording and each listed item earns its place.

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

Completeness4/5

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

The tool has no output schema skill, so the description compensates by listing the major returned components: columns, indexes, foreign keys, check constraints, and table-level statistics. It is sufficient for an agent to invoke the tool, though it could add a brief note about behavior on missing tables or privilege requirements.

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

Parameters3/5

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

Schema description coverage is 100%, and both parameters are already documented in the input schema, including the optional schema.table prefix. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource, 'Describe a table', and enumerates the returned metadata: columns, indexes, foreign keys, check constraints, and statistics. This clearly distinguishes the tool from sibling listTables, which would only list table names.

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 described output implies when to use the tool—when schema details such as columns, keys, and constraints are needed—but it does not explicitly state when not to use it or name alternatives like listTables for a simple table inventory. The usage context is inferable rather than specified.

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

explainQueryA

Return the estimated execution plan for a SELECT SQL query without actually executing it. The response format depends on the database engine (e.g. MSSQL, PostgreSQL, MySQL) and is returned as-is from the database driver.

ParametersJSON Schema

Name	Required	Description	Default
`sql`	Yes	SELECT SQL statement whose execution plan should be retrieved
`database`	No	Database in which to explain the query; omit to use the default

TDQS

A4.2/5.0

Behavior4/5

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

With no annotations, the description carries the full disclosure burden. It discloses important behavioral traits: the query is not actually executed, the output format varies by database engine, and the result is returned as-is from the driver. It could add more detail about potential cost or failure modes, but the core safety profile is clear.

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?

Two dense sentences with no wasted words. The most important behavior, not executing the query, is front-loaded, and the output-format caveat is delivered succinctly.

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

Completeness4/5

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

The description covers what input is expected, the non-execution guarantee, and the variability of the return payload. Since there is no output schema and no annotations, the description reasonably equips an agent to invoke the tool correctly, though it could more explicitly tie it to sibling selection.

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 explains both parameters. The description adds useful context about engine-dependent output but does not add meaning about individual parameters beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return'), resource ('estimated execution plan'), and scope ('SELECT SQL query'). It also explicitly distinguishes this from actually executing the query with 'without actually executing it', which separates it from sibling tools like 'query'.

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

Usage Guidelines4/5

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

The description gives clear usage context: use it to retrieve an estimated execution plan rather than execute a query. It also constrains usage to SELECT statements. It does not explicitly name alternative siblings or state when not to use it, so it stops short of a 5.

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

exportQueryA

Execute a read-only SELECT SQL query and stream the results to a file. Supports CSV and JSON output formats. Designed for large datasets – results are streamed directly to disk without a row-count limit. CSV options: delimiter (default ','), nullValue (default ''), bom (default false). JSON options: pretty (default false). Timeout is controlled by the EXPORT_QUERY_TIMEOUT environment variable (default: 300 s).

ParametersJSON Schema

Name	Required	Description
`sql`	Yes	SELECT SQL statement whose results should be exported
`format`	No	Output format. "csv" (default) or "json"
`options`	No	Format-specific options. CSV: delimiter (default ","), nullValue (default ""), bom (default false). JSON: pretty (default false). Additional keys are accepted for forward compatibility.
`database`	No	Database to query; omit to use the default
`filepath`	Yes	Destination file path (absolute, or relative to the server working directory)

TDQS

A4.1/5.0

Behavior4/5

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

With no annotations provided, the description carries the disclosure burden. It transparently covers read-only behavior, streaming, absence of row-count limits, format defaults, and timeout via environment variable. It does not mention behavioral details such as overwriting existing files or permission requirements, though the disclosed information is substantial.

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 front-loaded with the core purpose and each sentence carries useful information. There is slight redundancy between 'streamed directly to disk' and 'without a row-count limit', but overall it remains structured and efficient.

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

Completeness4/5

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

The description covers purpose, formats, default options, large-data streaming, and timeout behavior, which is strong for a tool with no annotations and no output schema. The main gap is the lack of explicit behavior around file overwriting or what the tool returns after completion.

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 parameters. The description mostly restates option defaults already present in the schema rather than adding new semantic meaning, keeping it at the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: executing a read-only SELECT query and streaming results to a file. It clearly differentiates this from the sibling 'query' tool by emphasizing file output and supporting CSV/JSON formats.

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

Usage Guidelines4/5

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

The description clearly implies when to use this tool: for large datasets needing disk streaming without row-count limits. It does not explicitly name alternatives like 'query' or specify when not to use it, but the intended context is evident.

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

listDatabasesA

List databases available to the tools. isDefault identifies the database used when database is omitted.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4/5.0

Behavior3/5

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions the isDefault field, which is a useful behavioral detail, but it does not state whether the operation is read-only, whether it requires authentication, or what the return format is beyond that field. For a simple list operation, this is adequate but not comprehensive.

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 sentence that front-loads the main purpose and includes a necessary clarification about isDefault. There is no wasted wording.

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

Completeness5/5

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

For a tool with no parameters and no output schema, the description is complete: it states what it does and clarifies a key output field. The low complexity means nothing essential is missing.

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

Parameters5/5

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

There are zero parameters, so the baseline is 4. The description adds value by explaining the isDefault field, which goes beyond the empty input schema and helps the agent interpret the output. This exceeds the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (List) and resource (databases), and it is distinct from sibling tools like listTables and query. It also provides a meaningful detail about isDefault, which helps the agent understand the result structure.

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 does not mention when to use this tool versus alternatives, nor does it give exclusions. An agent would have to infer that this is for discovering available databases, but there is no explicit guidance or comparison to siblings.

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

listTablesA

List all base tables in the database, returning their schema and name.

ParametersJSON Schema

Name	Required	Description	Default
`database`	No	Database to inspect; omit to use the default

TDQS

A3.8/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 does disclose that the operation returns schema and name, which implies a read-only metadata listing, but it does not mention potential costs, permission requirements, or whether only the default database scope is affected beyond the optional parameter. For a simple list operation this is adequate but minimal.

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 sentence that front-loads the main action and resource before mentioning return values. There is no redundant wording or filler.

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

Completeness4/5

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

For a tool with one optional parameter and no output schema, the description sufficiently communicates what the tool does and what it returns. It is complete enough to invoke correctly, though it could improve by explicitly distinguishing itself from describeTable.

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 coverage is 100% and the single optional parameter is already clearly described as 'Database to inspect; omit to use the default'. The description adds no new meaning beyond using the phrase 'in the database', so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and a clear resource ('all base tables'), and it states the returned information (schema and name). This distinguishes it from sibling tools like listDatabases, query, and describeTable without needing to inspect them.

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 clearly implies it should be used to enumerate base tables in a database, but it does not explicitly mention when to prefer a sibling tool such as describeTable or query. There are no exclusions or alternative routing statements, so the usage context is only implied.

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

queryA

Execute a read-only SELECT SQL query. Returns results in a compact column/row format to reduce token usage. Results are capped at 100 rows; use skip/take for pagination. The meta.totalCount field shows the total number of matching rows.

ParametersJSON Schema

Name	Required	Description
`sql`	Yes	SELECT SQL statement to execute
`skip`	No	Number of rows to skip (offset)
`take`	No	Maximum rows to return (max 100)
`database`	No	Database to query; omit to use the default database

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses key behaviors: read-only operation, compact column/row output to reduce tokens, a 100-row cap, pagination via skip/take, and the meta.totalCount field. It does not cover error handling or authentication, but for a query tool the core behaviors are well articulated.

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?

Three sentences with zero filler. The purpose is front-loaded, and each sentence adds a distinct piece of information (read-only, output format, pagination/totalCount). The structure is highly efficient.

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

Completeness4/5

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

For a query tool with no output schema, the description adequately covers the return format, row limits, and pagination. It does not mention error behavior or SQL dialect specifics, but these are not critical for basic invocation. Given the tool's complexity, the description is largely complete, though not exhaustive.

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

Parameters4/5

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by clarifying pagination semantics (skip/take) and the output format (compact format, totalCount field), which goes beyond the raw schema. This is useful behavioral context that helps the agent understand parameter interplay.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a read-only SELECT SQL query, which is specific and distinct from siblings like explainQuery (which explains) and exportQuery (which exports). The read-only constraint is explicitly mentioned, making the purpose unambiguous.

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

Usage Guidelines4/5

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

The description gives clear context for use: it's for read-only SELECT queries, with pagination guidance (use skip/take). It does not explicitly mention when not to use it or point to alternatives, but the context is sufficient for typical selection. No exclusions are stated, so it earns a 4.

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

saveQueryEvidenceA

Execute a read-only SELECT SQL query and save the SQL plus the results as a Markdown report file. Returns the saved file path, the total number of rows fetched, and the first 10 rows as preview data.

ParametersJSON Schema

Name	Required	Description
`sql`	Yes	SELECT SQL statement to execute and document
`database`	No	Database to query; omit to use the default
`filepath`	Yes	Destination Markdown file path (absolute, or relative to the server working directory)

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It does disclose the read-only/SELECT-only restriction, the file-writing side effect, and the three return values — good coverage. However, it is silent on file-overwrite behavior: whether an existing destination file is clobbered, appended to, or causes an error. That is a material omission for a tool whose side effect is writing a file.

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?

Two tight sentences that front-load the core action (execute + save as Markdown) and then state the return values. There is zero redundancy or filler; every clause earns its place.

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

Completeness4/5

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

With no output schema and no annotations, the description covers what would otherwise be missing: safety profile (read-only), return shape (file path, row count, 10-row preview), and input constraint (SELECT only). The only notable omission is overwrite/idempotency behavior for the destination file, which prevents a perfect score.

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 baseline is 3 even with no parameter detail in the description. The description adds only mild context (read-only constrains the sql parameter; the file path is the Markdown destination), but the schema already documents sql, database, and filepath semantics adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action chain — execute a read-only SELECT query and save the SQL plus results as a Markdown report file — and its return values. This clearly separates it from siblings like query (no file output), exportQuery (different export format/flow), and explainQuery (query-plan analysis, no persistence).

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 use case (producing documented evidence for later reference) is implied by the purpose, but no alternatives are named and no when-to-use vs. when-not-to-use guidance is given. With siblings query and exportQuery overlapping heavily in the query-execution space, explicit routing would materially help an agent pick correctly, and none is offered.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

7 tool updatesv0.3.0Sep 26, 2026

ChangeddescribeTable1 field changed

addedInput schema / properties / database

Added value: +{
+  "description": "Database containing the table; omit to use the default",
+  "minLength": 1,
+  "type": "string"
+}

ChangedexplainQuery1 field changed

addedInput schema / properties / database

Added value: +{
+  "description": "Database in which to explain the query; omit to use the default",
+  "minLength": 1,
+  "type": "string"
+}

ChangedexportQuery1 field changed

addedInput schema / properties / database

Added value: +{
+  "description": "Database to query; omit to use the default",
+  "minLength": 1,
+  "type": "string"
+}

AddedlistDatabases

ChangedlistTables1 field changed

addedInput schema / properties / database

Added value: +{
+  "description": "Database to inspect; omit to use the default",
+  "minLength": 1,
+  "type": "string"
+}

Changedquery1 field changed

addedInput schema / properties / database

Added value: +{
+  "description": "Database to query; omit to use the default database",
+  "minLength": 1,
+  "type": "string"
+}

ChangedsaveQueryEvidence1 field changed

addedInput schema / properties / database

Added value: +{
+  "description": "Database to query; omit to use the default",
+  "minLength": 1,
+  "type": "string"
+}

6 tool updatesv0.1.1Jul 13, 2026
- First observeddescribeTable
- First observedexplainQuery
- First observedexportQuery
- First observedlistTables
- First observedquery
- First observedsaveQueryEvidence

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

A4/5.0

Scored 2026-09-26 08:10 across 7 tools

Disambiguation4/5

Most tools have clearly distinct purposes: listing databases/tables, describing a table, explaining a query, and executing a query. query, exportQuery, and saveQueryEvidence all execute SELECT statements, but their output destinations are sufficiently different that an agent can choose correctly.

Naming Consistency4/5

The naming is mostly consistent camelCase verb_noun style: listDatabases, listTables, describeTable, explainQuery, exportQuery, saveQueryEvidence. The single exception is query, which lacks a verb prefix but is still clear and readable.

Tool Count5/5

Seven tools is a well-scoped set for a read-only SQL database MCP server. Each tool covers a distinct need without excessive overlap or unnecessary bloat.

Completeness4/5

The core read-only database workflow is well covered: discover databases, list tables, describe schema, run queries, explain query plans, and export or save results. Minor gaps such as listing views or schemas are workaroundable and do not cause dead ends.

Maintenance

ActivityMaintained

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Draxlr AOAuth
com.draxlr.api
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.
Data Visualization Databases Search
151
Dataassist-IOOAuth
io.github.DataAssistIO
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Search Databases
2
dataOAuth
co.thinair
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Databases Developer Tools
2
mcpOAuth
com.gibsonai
GibsonAI MCP server: manage your databases with natural language
Databases Search
233

Related MCP Servers

MSSQL MCP Python Server
Databases Observability
lorenzouriel
A
license
Not graded
quality
B
maintenance
MCP server for safely exposing SQL Server database capabilities to LLM clients, with read-only mode, security features, and observability.
Updated 2 months ago (2026-08-12 13:49 UTC)
28
MIT
sqlite-mcp-server
Databases
helmi75
A
license
Not graded
quality
D
maintenance
A read-only MCP server that enables LLMs to safely explore and query any SQLite database via natural language. It exposes tools for listing tables, describing schemas, and executing SELECT/WITH queries with built-in safety guards like write prevention and row limits.
Updated 3 months ago (2026-06-28 12:55 UTC)
MIT
ajan-sql
borakilicoglu
A
license
Not graded
quality
C
maintenance
An MCP server that provides safe, read-only SQL access for AI agents to query databases (PostgreSQL, MySQL, SQLite) with schema awareness and guardrails.
Updated 4 months ago (2026-05-25 09:40 UTC)
15 npm
MIT
Generic SQL MCP Server
Databases Search
Ayushedunext
F
license
Not graded
quality
B
maintenance
A configurable, database-agnostic MCP server that enables LLMs to safely interact with SQL databases through read-only operations and schema inspection.
Updated 2 months ago (2026-08-07 08:09 UTC)
-