Skip to main content
Glama
ugurcl

dbridge-mcp

by ugurcl
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

The agent discovers the schema on its own (list_tables, describe_table), then writes and runs a SELECT for whatever the user asks. No hand-written endpoint per question.

Works with SQLite, PostgreSQL, and MySQL / MariaDB.

Why

A raw LLM cannot know what is inside your database, and web search cannot reach private data. dbridge gives the model a guarded door to that data: it can read and answer, but it cannot write, drop, or leak the whole table.

Why dbridge and not another database MCP?

There are many database MCP servers. dbridge is built around one idea — you should be able to point an AI at a real database without holding your breath — and that shows up as a combination the single-engine servers don't offer:

  • One server, three engines. SQLite, PostgreSQL, and MySQL/MariaDB behind the same tools and the same config. Switch databases by changing the connection string, not the tooling.

  • Read-only twice over. A SQL guard rejects anything but SELECT/WITH and every query runs inside a database-enforced READ ONLY transaction — so even a query that outsmarts the guard cannot write.

  • Column-level privacy. Hide columns from the model entirely, or mask values (a***@site.com) while keeping them queryable. Most servers expose whatever the connection can see.

  • Blast-radius controls. Row caps enforced over user-supplied LIMITs, per-query timeouts, EXPLAIN-based cost rejection for expensive queries, per-minute rate limits, and a capped connection pool.

  • No native build step. SQLite uses Node's built-in node:sqlite, so npx -y dbridge-mcp works without a compiler toolchain.

  • Performance insight, not just queries. column_stats and index_health give the model real cardinality and index-usage data, and test_index simulates an index with hypopg before anyone builds it — so the model's optimization advice is grounded in the actual database instead of guesswork.

If all you need is "run SQL from my agent", plenty of servers do that. dbridge is for pointing an agent at data you actually care about.

Related MCP server: mcp-multi-db

Tools

Tool

Purpose

list_tables

List every table in the database.

describe_table

Return a table's columns, primary key, foreign keys, and row-count estimate.

sample_table

Preview the first rows of a table (json/csv/markdown).

count_rows

Return the exact row count of a table.

run_query

Run a single read-only SELECT / WITH and return rows as json, csv, or markdown.

explain_query

Return a query's plan and estimated cost without running it.

column_stats

Per-column distinct-value counts and null fractions — is this column selective enough to index?

index_health

List indexes with sizes and scan counts, flagging unused, duplicate, and invalid ones.

test_index

Simulate a CREATE INDEX without building it and report whether the planner would use it (PostgreSQL, via hypopg).

slow_queries

The most expensive recorded statements with call counts and timings (PostgreSQL pg_stat_statements, MySQL performance_schema).

get_limits

Report the safety limits in effect (caps, timeouts, hidden/masked columns).

Resources

Resource

Purpose

dbridge://schema

The full schema (every table and its columns) as one JSON document.

Prompts

Prompt

Purpose

optimize

A guided optimization pass: find slow queries, inspect plans and index health, and validate every index recommendation with test_index before suggesting it.

Requirements

Node.js 22.5+ (SQLite uses the built-in node:sqlite, no native build step).

Install

The published package ships a dbridge-mcp binary, so no clone or build step is needed to use it. Point it at a database with the connection argument:

npx -y dbridge-mcp demo.db                                  # SQLite (file path)
npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"  # PostgreSQL
npx -y dbridge-mcp "mysql://user:pass@host:3306/mydb"       # MySQL / MariaDB

The database engine is chosen from the connection string: a file path is SQLite, postgres:// / postgresql:// is PostgreSQL, and mysql:// is MySQL/MariaDB.

Or install it once, globally:

npm install -g dbridge-mcp
dbridge-mcp "postgresql://user:pass@host:5432/mydb"

MCP clients start the server for you as a subprocess — see the client sections below.

Windows note: MCP clients cannot launch npx directly on Windows because it is a .cmd script. Wrap it with cmd /c — use "command": "cmd" and put "/c", "npx", "-y", "dbridge-mcp", "<connection>" in the args. The examples below use the direct form (macOS/Linux); on Windows add the cmd /c prefix.

Use it in Claude Desktop

Claude Desktop only supports a single global config. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "dbridge": {
      "command": "npx",
      "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }
    }
  }
}

For a local SQLite file, replace the connection string with an absolute path to the .db file. Restart Claude Desktop, then ask: "what were the 5 best-selling products last month?"

Use it in Claude Code

Add it to the current project with the CLI:

claude mcp add dbridge --scope project \
  -e DBRIDGE_CONFIG=/absolute/path/to/dbridge.config.json \
  -- npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"

--scope project writes a shareable .mcp.json in the project root; use --scope user for a global server or omit it for a private per-project one. The .mcp.json looks like:

{
  "mcpServers": {
    "dbridge": {
      "command": "npx",
      "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }
    }
  }
}

Run claude from that directory; approve the project server once, then check it with /mcp.

Use it in Cursor

Add the same mcpServers block to .cursor/mcp.json in the project root (or ~/.cursor/mcp.json for all projects), enable the server under Settings → MCP, then ask the Agent a question about your data.

Use it in Windsurf

Add the same mcpServers block to ~/.codeium/windsurf/mcp_config.json, then refresh the server list under Settings → Cascade → MCP.

Use it in OpenCode

Add to opencode.json (project root or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dbridge": {
      "type": "local",
      "command": ["npx", "-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"],
      "enabled": true
    }
  }
}

To tune the safety guard, point the server at a config file with the environment block:

"environment": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }

Docker

Build the image and run the server over stdio:

docker build -t dbridge-mcp .
docker run --rm -i dbridge-mcp "postgresql://user:pass@host:5432/mydb"

Mount a config file and point DBRIDGE_CONFIG at it:

docker run --rm -i \
  -v "$PWD/dbridge.config.json:/config.json:ro" \
  -e DBRIDGE_CONFIG=/config.json \
  dbridge-mcp "postgresql://user:pass@host:5432/mydb"

Safety

  • The connection is opened read-only. On PostgreSQL and MySQL every query also runs inside a READ ONLY transaction, so writes are rejected by the database itself even if a query slips past the guard.

  • Only SELECT and WITH statements pass; writes, DDL, and data-modifying CTEs are rejected.

  • A single statement per call; the row cap is enforced even when a query supplies its own larger LIMIT (default 1000 rows).

  • Each PostgreSQL and MySQL query is bounded by a per-query timeout (statement_timeout / max_execution_time), so a runaway or expensive query cannot pin the database.

  • System catalogs and credential tables (information_schema, pg_authid, sqlite_master, …) are not queryable; schema discovery goes through the tools.

  • Restricted columns can be hidden entirely: the model cannot see them in the schema, query them, or receive them in results.

  • Tables can be restricted with an allow-list or block-list; blocked tables are invisible and unqueryable.

  • Columns can be masked instead of hidden: they stay visible but values come back partially redacted (e.g. a***@site.com).

  • Expensive queries can be rejected up front by an EXPLAIN cost estimate, and callers can be rate-limited per minute.

  • The connection pool size is capped, so dbridge cannot exhaust the database's connections.

Config

Every setting has three sources, in increasing precedence: a JSON file (DBRIDGE_CONFIG), environment variables, then CLI flags. So you can drop the JSON file entirely and set only what you need:

npx -y dbridge-mcp "postgresql://user:pass@host/db" --max-rows 200 --statement-timeout-ms 3000 --masked-columns email,iban
DBRIDGE_MAX_ROWS=200 DBRIDGE_REQUIRE_SSL=true npx -y dbridge-mcp "postgresql://user:pass@host/db"

Or keep everything in one place: point DBRIDGE_CONFIG at a JSON file (see dbridge.config.example.json for a full template). Every field is optional:

{
  "maxRows": 500,
  "hiddenColumns": ["ssn", "password_hash"],
  "maskedColumns": ["iban", { "column": "email", "strategy": "email" }],
  "allowedTables": ["products", "sales", "customers"],
  "blockedTables": ["employees", "audit_log"],
  "statementTimeoutMs": 5000,
  "maxCost": 100000,
  "rateLimitPerMin": 60,
  "maxPoolSize": 5,
  "connectionTimeoutMs": 10000,
  "requireSsl": true,
  "schemas": ["public", "reporting"],
  "auditLog": true
}

Field

CLI flag / env var

Default

Purpose

maxRows

--max-rows / DBRIDGE_MAX_ROWS

1000

Hard cap on rows returned per query, enforced even over a larger LIMIT.

hiddenColumns

--hidden-columns / DBRIDGE_HIDDEN_COLUMNS

[]

Columns hidden from the schema, queries, and results.

maskedColumns

--masked-columns / DBRIDGE_MASKED_COLUMNS

[]

Columns whose values are redacted in results (see below).

maxCellChars

--max-cell-chars / DBRIDGE_MAX_CELL_CHARS

0

Truncate any string cell longer than this; 0 disables.

maxResultBytes

--max-result-bytes / DBRIDGE_MAX_RESULT_BYTES

0

Cap the total serialized result size, dropping trailing rows; 0 disables.

allowedTables

--allowed-tables / DBRIDGE_ALLOWED_TABLES

[]

If non-empty, only these tables are exposed.

blockedTables

--blocked-tables / DBRIDGE_BLOCKED_TABLES

[]

Tables that are always hidden and unqueryable.

statementTimeoutMs

--statement-timeout-ms / DBRIDGE_STATEMENT_TIMEOUT_MS

10000

Per-query timeout (PostgreSQL statement_timeout, MySQL max_execution_time); 0 disables.

maxCost

--max-cost / DBRIDGE_MAX_COST

0

Reject queries whose EXPLAIN cost estimate exceeds this (PostgreSQL/MySQL); 0 disables.

rateLimitPerMin

--rate-limit-per-min / DBRIDGE_RATE_LIMIT_PER_MIN

0

Max query-executing tool calls per minute; 0 disables.

maxPoolSize

--max-pool-size / DBRIDGE_MAX_POOL_SIZE

5

Maximum pooled connections (PostgreSQL/MySQL).

connectionTimeoutMs

--connection-timeout-ms / DBRIDGE_CONNECTION_TIMEOUT_MS

10000

How long to wait for a connection (PostgreSQL/MySQL).

requireSsl

--require-ssl / DBRIDGE_REQUIRE_SSL

false

Require a verified TLS connection (PostgreSQL/MySQL).

schemas

--schemas / DBRIDGE_SCHEMAS

["public"]

PostgreSQL-only: schemas to expose; multiple schemas yield schema.table names.

auditLog

--audit-log / DBRIDGE_AUDIT_LOG

false

Log every tool call (query, rows, duration, errors) as JSON to stderr.

List values on the command line or in env vars are comma-separated (--allowed-tables products,sales).

Engine note: statementTimeoutMs, maxCost, maxPoolSize, connectionTimeoutMs, requireSsl, and schemas apply to the networked engines (PostgreSQL/MySQL). SQLite is a local file, so it ignores them; the row cap, column/table access control, and masking apply to every engine.

Column masking

maskedColumns keeps a column visible but redacts its values. Each entry is either a column name (defaults to the partial strategy) or an object { "column": ..., "strategy": ..., "keep": ... }:

Strategy

Example input

Output

partial (default)

TR120000123456

**********3456 (keeps the last keep, default 4)

email

ayse@site.com

a***@site.com

full

anything

***

Unlike hiddenColumns, a masked column can still be used in WHERE/GROUP BY, so use hiddenColumns for true secrets and maskedColumns for values that should be recognizable but not exposed.

Output formats

run_query and sample_table take an optional format argument: json (default, full result object), csv, or markdown. CSV and Markdown return a compact table prefixed with a short rows: N · Nms header — handy for fewer tokens and readable output. Combine with maxCellChars and maxResultBytes to keep large results in check.

Running against a production database

  • Pass the connection string via the DBRIDGE_DB_PATH environment variable instead of the command line, so the password does not appear in the process list.

  • Prefer a dedicated database role with read-only grants on only the tables you want exposed — that is the real security boundary; the guard is defense in depth.

  • Set a conservative statementTimeoutMs, maxRows, and maxCost, and use allowedTables to expose only reporting tables.

Local development

To hack on dbridge itself, clone the repo and build from source:

npm install
npm run build
npm run seed        # creates demo.db (a small store: products, customers, sales)
node dist/index.js demo.db

Try it with the MCP Inspector

npm run inspect

Then call the tools from the Inspector UI. No LLM or API key needed.

Tests

npm test

Changelog

See CHANGELOG.md.

License

MIT

Available Tools

7 tools
count_rowsCount table rowsB

Returns the exact number of rows in a table.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesExact table name

TDQS

B3.4/5.0
Behavior2/5

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

No annotations provided, so the description carries full burden. Only states 'returns exact number of rows' without disclosing performance, locking, or side effects. Minimal.

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?

One efficient sentence without wasted words. Could be slightly expanded but front-loaded.

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

Completeness3/5

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

Adequate for a simple tool with one parameter and no output schema, but lacks behavioral details like performance implications or prerequisites.

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% with the 'table' parameter described as 'Exact table name'. The description adds no additional meaning beyond the schema.

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 returns the exact number of rows in a table, using a specific verb and resource. It distinguishes itself from siblings like describe_table or run_query.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives like run_query with COUNT(*). The purpose is obvious but lacks context for selection.

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

describe_tableDescribe tableA

Returns the columns of a table (name, type, nullability). Use it before writing a query.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesExact table name, e.g. sales

TDQS

A3.6/5.0
Behavior3/5

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

No annotations provided, so description is the sole source. It states the tool returns column metadata (name, type, nullability). It does not disclose error handling, permissions, or whether it checks table existence. The behavior is partially transparent but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two short sentences that front-load the purpose and add a usage hint. No redundant or extra words.

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?

Given the tool's simplicity (one parameter, simple return), the description adequately states what it returns and suggests when to use it. It could mention error behavior or ordering, but it is largely complete for a metadata tool.

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% with a clear parameter description. The tool description adds no new meaning beyond what the schema already provides, resulting in a baseline score.

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

Purpose4/5

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

The description clearly states it returns table columns with name, type, and nullability. It uses the verb 'Returns' and specifies the resource. It does not explicitly differentiate from sibling tools like list_tables or sample_table, but its purpose is distinct.

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 includes 'Use it before writing a query', implying a recommended use case. However, it lacks explicit when-not-to-use guidance or alternatives among siblings.

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

explain_queryExplain a queryA

Returns the query plan and estimated cost without running the query. Use it to check a query is cheap before running it.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesA single read-only SELECT or WITH statement to analyze

TDQS

A4.8/5.0
Behavior5/5

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

Discloses that the query is not executed and only analyzed, making it safe. Also specifies that input must be read-only SELECT or WITH, covering security constraints.

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 concise sentences; first tells what it does, second tells when to use it. No unnecessary words.

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?

Covers all essential aspects: output (query plan and cost), parameter constraint, and usage context. With no output schema, the description adequately fills the gap.

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?

Adds value beyond schema by requiring the SQL to be a single read-only SELECT or WITH statement, which is not in the schema description.

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?

Clearly states it returns the query plan and estimated cost, differentiating from run_query which executes. The verb 'Returns' and resource 'query plan' are specific.

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?

Explicitly recommends using it to check if a query is cheap before running it. Lacks explicit when-not-to-use, but the contrast with run_query is implied.

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

get_limitsGet active limitsA

Returns the safety limits in effect (row cap, timeout, cost/rate limits, hidden and masked columns, table allow/block lists).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior4/5

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

No annotations are provided, so the description shoulders full burden. It explicitly states 'Returns', indicating a read-only operation with no side effects. It lists the types of limits returned, giving sufficient behavioral insight for safe invocation.

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 purpose and enumerates return values efficiently. No wasted words.

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 parameterless tool that returns safety limits, the description is complete: it lists what is returned. No output schema exists, but the description covers the essential return categories, making it fully actionable.

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

Parameters4/5

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

The tool has zero parameters, so the baseline is 4. The schema description coverage is 100% (no parameters to document), and the description adds no further parameter information, which 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 clearly states the tool returns safety limits, listing specific categories (row cap, timeout, cost/rate limits, etc.). This distinguishes it from sibling tools like run_query, count_rows, etc., which focus on data operations rather than configuration limits.

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

Usage Guidelines3/5

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

The description implies usage when an agent needs to know current safety limits, but it does not explicitly state when to use or avoid this tool, nor does it mention alternatives. The context is clear enough for a simple read operation.

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

list_tablesList tablesA

Lists every table in the connected database. Call this first to discover what data is available.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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

No annotations are provided, so the description carries full burden. It states it lists tables, which is non-destructive, but doesn't cover permissions, performance, or result format, leaving minor gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and usage, no superfluous content. 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 zero-parameter discovery tool, the description is adequate. It lacks details about output format (e.g., table names vs. schemas), but sibling 'describe_table' handles specifics, so completeness is reasonable.

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?

No parameters exist, so schema coverage is 100%. The description doesn't need to add param info, earning a baseline score of 4.

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 it lists every table in the database, using a specific verb and resource. It distinguishes from siblings like 'describe_table' and 'run_query' that have different purposes.

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?

Explicitly advises to call this first to discover data, providing clear context for when to use it. While it doesn't list exclusions, the sibling tools implicitly cover 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_queryRun a read-only SQL queryA

Runs a single read-only SELECT or WITH statement and returns the rows as JSON. Writes are rejected and results are capped.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesA single read-only SELECT or WITH statement, written in the connected database's SQL dialect
formatNoOutput format for the rows: json (default), csv, or markdown

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 full burden. It discloses critical behaviors: read-only enforcement, result capping, and default JSON output. However, it omits details on error handling, pagination, 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence conveys the tool's action, constraints, and output. Every word adds value; no redundancy 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?

Given the tool's complexity (2 parameters, no output schema), the description provides essential context: read-only, results capped, output format options. It could mention result structure (array of row objects) or error responses, but is mostly complete.

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

Parameters4/5

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

The input schema covers both parameters (sql, format) with descriptions. The description adds value beyond the schema by specifying 'single' statement, 'read-only', and 'capped results'. This clarifies constraints not in the schema.

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 explicitly states the verb (runs), resource (SQL query), and constraints (read-only, SELECT/WITH, capped results). It clearly distinguishes the tool's purpose from sibling tools, which are more specific (e.g., count_rows, describe_table).

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

Usage Guidelines3/5

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

The description implies appropriate use cases (arbitrary read-only queries) but does not explicitly contrast with sibling tools or provide when-not-to-use guidance. For a general query tool, this is adequate but not outstanding.

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

sample_tableSample table rowsB

Returns the first rows of a table as a quick preview, to understand the data before querying.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoRows to preview, default 10
tableYesExact table name
formatNoOutput format for the rows: json (default), csv, or markdown

TDQS

B3.4/5.0
Behavior2/5

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

With no annotations provided, the description bears full burden for behavioral disclosure. It only states the tool returns rows, omitting important traits like non-destructiveness, error handling (e.g., nonexistent table), performance, or that it's a read-only operation. This leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, concise and front-loaded with the core action. It wastes no words. However, it could be slightly more structured (e.g., separating purpose from usage context) though still efficient.

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

Completeness3/5

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

Given the tool's simplicity (preview rows) and absence of output schema, the description is adequate but minimal. It doesn't mention output format defaults or that preview is limited to first rows. It provides enough context for a simple tool but could be more complete.

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

Parameters3/5

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

Schema description coverage is 100%, meaning the input schema already documents all three parameters. The description adds no extra meaning or usage context for the parameters beyond what the schema provides, so it meets the baseline but doesn't elevate understanding.

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 ('Returns') and resource ('first rows of a table'), clearly distinguishing it from sibling tools like count_rows (counts rows) and describe_table (schema). It also states the intent ('quick preview, to understand the data before querying'), 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 Guidelines3/5

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

The description implies usage context ('before querying') but does not explicitly state when not to use this tool or provide alternatives to sibling tools. It offers some guidance but lacks exclusion criteria or comparative advice.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: listing tables, describing schema, counting rows, sampling data, explaining queries, checking limits, and running queries. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_tables, describe_table, run_query). Verbs are descriptive and predictably used.

Tool Count5/5

Seven tools are appropriate for a database bridge server, covering essential read-only operations like discovery, schema inspection, preview, counting, and safe query execution.

Completeness5/5

The tool set covers the full lifecycle of read-only database exploration: discover tables, describe schema, preview data, count rows, check limits, plan and execute queries. No obvious gaps for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • postgres-mcp-query-tool

    nskha101
    F
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that gives an AI agent scoped, safe access to your Postgres databases with per-connection access control, row caps, timeouts, and defense-in-depth read-only enforcement.

  • mcp-multi-db

    mahAnuj
    A
    license
    A
    quality
    A
    maintenance
    Read-only MCP server for querying PostgreSQL, MySQL, and SQLite from AI agents — multi-database, safe by default.
    4
    18
    1
    ISC

  • Universal Database MCP

    jaynasriwala
    F
    license
    Not graded
    quality
    B
    maintenance
    A small MCP server that lets an LLM query PostgreSQL, MySQL, MariaDB, SQL Server, or SQLite databases safely — read-only, role-restricted, and with sensitive data blacked out.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ugurcl/dbridge-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server