Allows querying an Azure Database for PostgreSQL Flexible Server, including server discovery, catalog inspection, and read-only SQL execution using Azure CLI authentication.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SQMCPaL what tables are in the database?"
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.
An MCP server that lets any MCP-compatible AI tool query your Azure Database for PostgreSQL Flexible Server — no service principals, no connection strings in config files, no passwords anywhere. Just az login and go.
Works with Claude Code, GitHub Copilot CLI, Claude Desktop, GitHub Copilot in VS Code, and any other tool that speaks the Model Context Protocol.
You will never copy-paste a password from the Azure Portal. SQMCPaL authenticates with the Azure CLI session already on your machine, exchanging it for a short-lived Microsoft Entra token that is used as the database password. Nothing is stored, nothing to rotate, nothing to leak.
You don't need to know your schema. Ask your AI tool "what's in this database?" and it will walk the catalog — tables, columns, types, keys, indexes — before writing a single query.
It cannot write to your database. Read-only isn't a promise in the docs, it's enforced by PostgreSQL itself. See How read-only is enforced.
SQMCPaL is the SQL sibling of two existing MCP servers built on the same idea — your az login session is already the credential, so a local read-only MCP server needs no infrastructure at all:
SQMCPaL | |||
Target | Cosmos DB (MongoDB API) | Azure Storage (Blob/Queue/File/Table) | PostgreSQL Flexible Server |
Auth |
|
|
|
Operations | Read-only | Read-only | Read-only |
Runs as | Local stdio server | Local stdio server | Local stdio server |
Same shape, same guarantees, different data store. If you already run one of the others, this one will feel identical.
Related MCP server: postgres-mcp-server
Auto-discovery — lists every PostgreSQL flexible server your Azure credential can see, across all subscriptions
Session context — connect once, then query without repeating server/database/schema on every message
Catalog inspection — databases, schemas, tables, sizes, row estimates, columns, primary keys, indexes, foreign keys
Arbitrary read SQL — full SELECT power including joins, CTEs, window functions and EXPLAIN
Convenience tools — count_rows, distinct_values, sample_rows for the questions you ask constantly
Passwordless — Entra token minted per session from your own CLI login, auto-refreshed before expiry
Read-only, enforced by the server — not by a regex
Azure CLI (brew install azure-cli), logged in with az login
Python 3.11+ (or uv, which is easier — see Setup)
An Azure Database for PostgreSQL Flexible Server you can reach on the network
Your Entra identity must be able to log into that server (see below)
PostgreSQL will reject your login unless your Entra principal exists as a role on the server. Either:
Set yourself as the Microsoft Entra admin on the server (Portal → your server → Authentication → Microsoft Entra admin), or
Have an existing Entra admin create a role for you:
SELECT * FROM pgaadauth_create_principal('you@example.com', false, false);
GRANT CONNECT ON DATABASE yourdb TO "you@example.com";
GRANT USAGE ON SCHEMA public TO "you@example.com";
GRANT SELECT ON ALL TABLES IN SCHEMA public TO "you@example.com";Entra authentication must be enabled on the server (Authentication → "Microsoft Entra authentication only" or "PostgreSQL and Microsoft Entra authentication").
Run check_auth from your AI tool at any time to see which role SQMCPaL will try to log in as.
Flexible servers are firewalled by default. Either add your IP under Networking → Firewall rules, or be on the server's VNet if it uses private access. If a connection hangs and then fails, this is almost always why.
claude mcp add sqmcpal -- uvx --from git+https://github.com/ChingEnLin/SQMCPaL sqmcpalAdd to ~/.copilot/mcp-config.json:
{
"mcpServers": {
"sqmcpal": {
"type": "local",
"command": "uvx",
"args": ["--from", "git+https://github.com/ChingEnLin/SQMCPaL", "sqmcpal"],
"tools": ["*"]
}
}
}Then start copilot and run /mcp to confirm it loaded.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"sqmcpal": {
"command": "uvx",
"args": ["--from", "git+https://github.com/ChingEnLin/SQMCPaL", "sqmcpal"]
}
}
}Restart Claude Desktop afterwards.
git clone https://github.com/ChingEnLin/SQMCPaL.git
cd SQMCPaL
uv venv --python 3.12 && uv pip install -e .then point command at /absolute/path/to/SQMCPaL/.venv/bin/sqmcpal with no args.
Talk to it in plain language. A typical first session:
You: What PostgreSQL servers do I have in Azure? AI: (list_postgres_servers) One —
database-patient-serverin germanywestcentral, PostgreSQL 16.You: Connect to it and show me what's in there. AI: (connect_server → list_databases → list_tables) Database
patientshas 8 tables inpublic; the biggest isappointmentsat ~1.2M rows.You: What does the appointments table look like, and how many are cancelled? AI: (describe_table → count_rows) 14 columns, PK on
id, FK topatients.id. 43,207 rows havestatus = 'cancelled'.You: Show me cancellations per month for the last year. AI: (run_query with a date_trunc + GROUP BY) …
You rarely name a tool yourself — set the context once and ask questions.
SQMCPaL asks DefaultAzureCredential for a token scoped to https://management.azure.com/.default and uses it to enumerate flexible servers via ARM.
For the database connection it requests a second token scoped to https://ossrdbms-aad.database.windows.net/.default.
That token is the PostgreSQL password. The login role is read from the token's own upn claim, so it always matches the identity you logged in as.
Tokens are refreshed automatically five minutes before expiry; pooled connections are re-established with the fresh token.
No credential is ever written to disk or into config. On a laptop this resolves to your az login session; in a container or CI it resolves to whatever managed identity or service principal is present.
Three independent layers, because one is not enough:
Every statement runs inside an explicit BEGIN READ ONLY transaction that is always rolled back. PostgreSQL rejects INSERT/UPDATE/DELETE/CREATE/DROP/ALTER/GRANT itself — this is the real guarantee, not client-side filtering.
The session default is read-only too (default_transaction_read_only = on), covering anything outside an explicit transaction.
Submitted SQL must be a single statement starting with SELECT, WITH, TABLE, VALUES, EXPLAIN or SHOW. This closes the one hole in layer 1: COMMIT; BEGIN READ WRITE; DELETE FROM … would otherwise escape the read-only transaction. The parser understands string literals, dollar-quoting and comments, so a semicolon inside 'a;b' is not mistaken for a statement separator.
There are no write tools in the registry, so there is nothing for a model to call even if it wanted to. Queries also carry a 30s statement_timeout so a runaway scan can't sit on your production server.
For belt-and-braces, grant the Entra role SELECT only — then the database itself is the fourth layer.
Tool | What it does |
| Verify the Azure credential and show the PostgreSQL login role it maps to |
| Every flexible server visible to your credential, across subscriptions |
| Connect by ARM resource ID; optionally set default database and schema |
| Databases on the connected server, with owner, encoding and size |
| Schemas in a database, with owner and table count |
| Tables, views and materialized views, with estimated rows and size |
| Columns, types, nullability, defaults, primary key, indexes, foreign keys |
| A few rows from a table, to see what the data actually looks like |
| Any single read-only SQL statement |
| Exact row count, optionally filtered by a |
| Distinct values of a column with frequencies, most common first |
| Inspect, change or reset the session |
Variable | Default | Purpose |
|
| Hard cap on rows returned by any tool |
|
| Server-side query timeout |
|
| Connection timeout in seconds |
|
| libpq sslmode |
|
| Server port |
| (token | Override the login role, if it differs from your UPN |
| — | Pre-fetched ARM token, for containers without the az CLI |
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
pre-commit installChecks (there is no integration suite — the DB layer is verified by connecting to a real server):
python test_sqmcpal.py # read-only SQL guard self-check
pre-commit run --all-files # ruff + ruff-format + mypy --strictprintf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
| .venv/bin/sqmcpalExpect "serverInfo":{"name":"sqmcpal",...} on stdout.
docker build --platform linux/arm64 -t sqmcpal:dev . # linux/amd64 on Intel/LinuxMount ~/.azure read-only into the container so the CLI session is available, or pass AZURE_ACCESS_TOKEN.
password authentication failed for user "you@example.com"
Your Entra principal isn't a role on that server. See Granting your Entra identity access.
Connection hangs, then "could not reach host" Firewall. Add your IP under the server's Networking blade, or connect from its VNet.
Azure credential not found or expired
Run az login in a terminal, then restart your MCP client so it picks up the refreshed session.
Only read-only statements are permitted
Working as intended. If your query legitimately starts with something else, wrap it — e.g. WITH x AS (…) SELECT ….
Multiple SQL statements are not allowed
Send one statement at a time. This is the guard that keeps a read-only transaction from being committed out from under itself.
Permission denied for a table you can see
list_tables reads the catalog, which is world-readable; reading rows needs GRANT SELECT. Ask an admin for the grant.
Flexible Server only. Single Server is retired and not supported; Cosmos DB for PostgreSQL is untested.
Microsoft Entra authentication only. Native PostgreSQL username/password logins are deliberately not supported — that would mean a secret in a config file.
One connection at a time. A single in-process session, matching one developer at one keyboard.
Read-only, permanently. Write tools will not be added. Point it at production on purpose.
MIT — see LICENSE.
Check whether the current Azure credential is valid for Azure Database for PostgreSQL Flexible Server access, and show which PostgreSQL login role it maps to.
Call this first if you suspect an authentication problem.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false, so the safety profile is known. The description adds that the tool maps credentials to a PostgreSQL login role, which is an observable behavior, and frames it as a preliminary diagnostic without side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, followed by a usage tip. No wasted words; every sentence contributes.
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 zero parameters, existing annotations, and an output schema, the description fully covers what the tool does and when to invoke it. It is appropriate for a simple diagnostic 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?
The tool has 0 parameters, so the schema already provides complete coverage. The description doesn't need to explain parameters; the baseline of 4 applies.
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 identifies the tool as a diagnostic for Azure credential validity in PostgreSQL Flexible Server, with a specific action 'Check' and output 'show which PostgreSQL login role it maps to'. It is distinct from sibling tools by focusing on authentication status rather than connection or querying.
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 explicitly states 'Call this first if you suspect an authentication problem', providing a clear condition for use. It doesn't specify when not to use it or mention alternative tools, but the guidance is direct and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Disconnect from the current PostgreSQL server, close pooled connections and clear session state.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context beyond the annotations: it explicitly says 'close pooled connections' and 'clear session state', giving the agent a clearer picture of side effects. This is consistent with readOnlyHint=true since it changes connection state rather than data.
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, succinct sentence that directly states the action and its effects. It is front-loaded with the main verb and resource, and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and an output schema present, the description fully captures the tool's behavior. There is no need to explain return values because an output schema exists, and the description covers the core action sufficiently.
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 tool has zero parameters, so the description does not need to explain parameter details. Per the rubric, a 0-parameter tool gets a baseline of 4, and the description adequately focuses on behavior rather than inputs.
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 uses a specific verb ('Disconnect') and identifies the resource ('current PostgreSQL server'), also adding concrete actions ('close pooled connections and clear session state'). This clearly distinguishes it from siblings like connect_server, show_context, and set_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but does not explicitly say when to use it versus alternatives. The intended usage (cleanup after a session) is implied rather than stated, and no exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Connect to a PostgreSQL flexible server by its ARM resource ID.
Resolves the server FQDN and stores it in session context. The password is a short-lived Microsoft Entra token minted from your own Azure login — nothing is stored on disk.
Args: server_id: ARM resource ID of the flexible server (from list_postgres_servers). server_name: Human-readable server name, for display. Defaults to the ARM name. database: Optional default database for subsequent calls. schema: Optional default schema. Defaults to 'public' when unset.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | ||
| database | No | ||
| server_id | Yes | ||
| server_name | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only and non-destructive. The description adds meaningful context: the password is a short-lived Microsoft Entra token minted from the user's Azure login, nothing is stored on disk, and the connection state is stored in session context. This goes well beyond the annotation hints.
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 front-loaded with the core action, followed by a concise security note and a compact Args list. Every sentence contributes useful information, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, prerequisite source (list_postgres_servers), authentication behavior, parameter meanings, and session side effects. Since an output schema exists, not explaining return values is acceptable. This is complete for an AI agent to select and invoke the tool 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?
The input schema provides no parameter descriptions (0% coverage). The description's Args section fully compensates by explaining server_id's origin, server_name's display purpose, database as an optional default, and schema defaulting to 'public'. This gives the agent everything it needs to fill parameters correctly.
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 connects to a PostgreSQL flexible server by ARM resource ID, resolves FQDN, and stores it in session context. This specific action distinguishes it from sibling tools like list_tables or run_query, which operate independently of connection setup.
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 references list_postgres_servers as the source for server_id and notes defaults for subsequent calls, implying it is a prerequisite for later query tools. However, it does not explicitly state when not to use it or name alternative connection methods, so it falls short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count rows in a PostgreSQL table, optionally filtered by a WHERE clause.
Exact, unlike the estimates from list_tables, and returns no row data.
Args: table: Table name. where: Optional WHERE clause body without the WHERE keyword, e.g. "status = 'active'". schema: Schema name. Defaults to the session schema, then 'public'. database: Database name. Defaults to the session database.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| where | No | ||
| schema | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=true and destructiveHint=false, the safety profile is covered. The description adds meaningful behavioral context: exactness (not an estimate), no row data in the result, and default resolution for schema and database. This goes beyond annotations, though it does not mention potential performance characteristics on large tables.
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 compact yet comprehensive, with a clear purpose statement followed by a bulleted Args list. Every sentence adds value: the first sentence states the function, the second highlights key differentiators (exactness and no row data), and the Args section documents parameters. No wasteful words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple count tool with four parameters, an output schema already defined, and annotations covering safety, this description is complete. It covers all parameter semantics, defaults, and the tool's core value proposition. The output schema handles return-value details, so this description fully satisfies the contextual needs.
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 the schema provides no parameter descriptions. The description's Args section compensates fully by explaining each parameter: table name, WHERE clause body (with example), schema defaulting behavior, and database defaulting behavior. This adds substantial meaning beyond the bare schema fields.
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 opens with 'Count rows in a PostgreSQL table, optionally filtered by a WHERE clause', which specifically identifies the action (count) and resource (PostgreSQL table). It further distinguishes itself from sibling tools by contrasting with list_tables' estimates, making its purpose unmistakable.
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 explicitly states it is 'Exact, unlike the estimates from list_tables', providing a direct when-to-use comparison. It also notes 'returns no row data', which implies when not to use this tool if row data is needed, giving clear contextual guidance (e.g., use sample_rows or run_query for actual rows).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe a PostgreSQL table: columns with data types, nullability and defaults, plus primary key, indexes and foreign keys.
Use this before writing a query against an unfamiliar table.
Args: table: Table, view or materialized view name. schema: Schema name. Defaults to the session schema, then 'public'. database: Database name. Defaults to the session database.
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | ||
| schema | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds value by detailing exactly what metadata is returned (columns, types, nullability, defaults, keys, indexes). This goes beyond the annotations without contradicting them.
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?
Concise and well-structured: a clear purpose statement, a usage recommendation, and a parameter list. No filler or redundancy; every sentence contributes meaning.
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 an output schema present, the description does not need to detail return values. It covers purpose, usage, and parameters sufficiently for the tool's complexity.
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%, so the description carries full responsibility for parameter meanings. The Args section fully explains each parameter, including parameter-specific behavior (e.g., schema defaults to session schema then 'public', database defaults to session database).
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 describes a PostgreSQL table with specific details (columns, types, nullability, defaults, keys, indexes). This distinguishes it from sibling tools like list_tables (which lists table names) and sample_rows (which shows 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?
Explicitly says 'Use this before writing a query against an unfamiliar table,' providing clear context for when to use it. However, it does not explicitly mention alternatives or when not to use it, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the distinct values of a column with their frequencies, most common first.
Useful for understanding enums, categories and cardinality.
Args: table: Table name. column: Column name. where: Optional WHERE clause body without the WHERE keyword. limit: Max distinct values to return (default 100). schema: Schema name. Defaults to the session schema, then 'public'. database: Database name. Defaults to the session database.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| table | Yes | ||
| where | No | ||
| column | Yes | ||
| schema | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool read-only and non-destructive. The description adds behavioral context about output ordering (frequencies, most common first), default limit, and schema/database fallback behavior, which goes beyond the annotations and enriches understanding.
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 very concise and well-structured: a one-sentence summary, a use-case note, and a labeled Args list. Every sentence is informative and there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers the tool's purpose, parameter semantics, defaults, and behavioral nuances. For a read-only analytical tool, this is complete enough for an agent to select and invoke it 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?
Despite 0% schema description coverage, the description includes an 'Args' section that explains every parameter in plain language, including meaning, optionality, and defaults. This fully compensates for the schema's lack of descriptions and provides clear usage guidance.
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 gets distinct values of a column with their frequencies, ordered most common first. This specific verb-resource combination distinguishes it from siblings like sample_rows, count_rows, and describe_table.
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 explicitly says the tool is useful for understanding enums, categories, and cardinality, giving clear context for when to use it. However, it does not mention any alternatives or exclusions compared to sibling tools, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all databases on the currently connected PostgreSQL flexible server, with owner, encoding and on-disk size. Azure-managed system databases are hidden.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds value by revealing that Azure-managed system databases are hidden and that output includes owner, encoding, and size. This supplements the annotations with useful behavioral context without contradiction.
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, front-loaded sentence that immediately states the action and resource, then provides key details. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and an output schema present, the description is fully sufficient. It covers scope (currently connected server), output fields (owner, encoding, size), and filtering behavior (hides Azure-managed DBs), making it complete for an agent to select and invoke 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?
The tool has zero parameters, so the schema provides full coverage (100%). The description does not need to explain parameters. Baseline for 0 params is 4, and no additional param semantics are required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all databases on the currently connected PostgreSQL flexible server, with owner, encoding and on-disk size.' It uses a specific verb and resource, and the mention of database listing clearly distinguishes it from sibling tools like list_tables and list_schemas.
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 phrase 'currently connected' implies a prerequisite (connection must be established) and provides clear context for when to use this tool. However, it does not explicitly mention alternatives or when not to use it, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Azure Database for PostgreSQL Flexible Servers accessible via the current Azure credential (az login / managed identity).
Returns server names, ARM resource IDs, FQDNs, subscriptions, locations and engine versions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds meaningful context about authentication ('via the current Azure credential (az login / managed identity)') and specifies the return fields (server names, ARM resource IDs, FQDNs, subscriptions, locations, engine versions), going beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states purpose and scope, the second lists return fields. It is front-loaded, concise, and contains no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters) and the presence of an output schema, the description adequately covers the essential context: what it lists, the auth scope, and the type of data returned. It is complete for this 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?
The tool has zero parameters, so the schema provides no semantics. The description does not need to explain parameters, and no additional parameter meaning is necessary. Baseline of 4 is appropriate for a no-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'List all Azure Database for PostgreSQL Flexible Servers accessible via the current Azure credential.' This clearly distinguishes it from sibling tools like list_databases and list_tables, which operate at different levels.
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 the tool is for discovering accessible PostgreSQL servers but does not explicitly state when to use it over alternatives. No when-not or alternative tool guidance is provided, so usage is inferred from the action itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the schemas in a PostgreSQL database with their owner and table count.
Args: database: Database name. Defaults to the session database.
| Name | Required | Description | Default |
|---|---|---|---|
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds value by noting the output includes owner and table count, and that the database parameter defaults to the session database, which are useful behavioral details beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with an Args section. It is front-loaded with the purpose and avoids unnecessary verbosity; every word contributes to understanding.
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 simple nature of the tool, the presence of an output schema, and annotations covering safety, the description provides all necessary information. It explains the single parameter and what the tool returns, making it complete.
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 sole parameter 'database' is fully explained in the description, including its default behavior. Since schema description coverage is 0%, the description carries the full burden and does so effectively.
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 lists schemas in a PostgreSQL database, including owner and table count. This distinguishes it from siblings like list_tables and list_databases by specifying the resource (schemas) and output details.
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 when schema-level information is needed, but it does not explicitly contrast with alternatives or provide when-not-to-use conditions. Sibling tools are present but no direct comparison is given, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables, views and materialized views in a PostgreSQL database, with estimated row counts and total size.
Args: database: Database name. Defaults to the session database. schema: Optional schema filter. Omit to list every non-system schema.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds behavioral context beyond that: it states the tool returns estimated row counts and total size, and clarifies that omitting the schema filter lists every non-system schema. This gives useful behavioral expectations.
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 compact and front-loaded: the main purpose is in the first sentence, followed by brief parameter notes. Every sentence adds value, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-only listing operation. Annotations cover safety, an output schema exists so return values are defined, and the description adequately explains scope (tables/views/materialized views) and filtering. There is no missing information that would impede correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions, but the description fully explains both parameters: database (defaults to session database) and schema (optional filter, omit for all non-system schemas). This directly compensates for the 0% schema coverage and adds meaningful semantics.
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 a specific action (list) with a specific resource (tables, views, materialized views) and adds detail about what is included (estimated row counts and total size). This distinguishes it from sibling tools like list_schemas or list_databases, which have different targets.
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 when to use this tool (to list tables/views/materialized views) but provides no explicit guidance on when to prefer it over alternatives, nor does it mention exclusions. For example, it does not say 'use this instead of describe_table'. Usage is implied by the purpose but not explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a read-only SQL statement against the connected PostgreSQL database.
Only a single SELECT / WITH / TABLE / VALUES / EXPLAIN / SHOW statement is accepted, and it runs inside a READ ONLY transaction that is always rolled back — writes are rejected by PostgreSQL itself.
Example: SELECT status, count(*) FROM public.orders GROUP BY status ORDER BY 2 DESC
Args: sql: A single read-only SQL statement. limit: Max rows to return (default 100). database: Database name. Defaults to the session database.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds valuable execution details: the statement runs inside a READ ONLY transaction that is rolled back, and PostgreSQL rejects writes. It also mentions the limit default and database default, enhancing behavioral understanding beyond annotations.
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 well-structured and concise: a one-line purpose, followed by key constraints, a concrete example, and a clean argument list. Every sentence contributes meaning with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a query tool: it states the read-only guarantee, allowed statement types, parameter semantics, and gives an example. Since an output schema exists, return value documentation is unnecessary. The only minor omission is a mention of connection prerequisites, but the phrase 'connected PostgreSQL database' implies an established context.
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 schema provides no property descriptions (0% coverage), so the description must compensate. It does so thoroughly, explaining sql as a single read-only statement, limit as max rows with default 100, and database as the database name defaulting to the session database. An example query further clarifies sql syntax.
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 a read-only SQL statement against the connected PostgreSQL database. This specific verb+resource combination distinguishes it from sibling tools like list_tables or describe_table, which focus on schema inspection rather than arbitrary queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: for executing read-only SQL of specific statement types (SELECT, WITH, etc.) and notes that writes are rejected. It does not explicitly name alternative tools, but the constraints and read-only scope effectively guide usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a handful of rows from a table to see what the data actually looks like.
Equivalent to SELECT * FROM schema.table LIMIT n.
Args: table: Table name. limit: Rows to return (default 10). schema: Schema name. Defaults to the session schema, then 'public'. database: Database name. Defaults to the session database.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| table | Yes | ||
| schema | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and non-destructive, and the description adds behavioral detail by specifying the operation as 'SELECT * LIMIT n', including default row limit and schema/database resolution (session schema then 'public'). This goes beyond the annotations.
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 compact, front-loaded with a clear summary, then a SQL equivalence, and then a tidy Args list with defaults. Every sentence adds value.
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 an output schema present, the description doesn't need to detail return values. It covers the core functionality, defaults, and fallback behavior for a simple sampling tool. It could mention anything about edge cases, but not required for this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It explains each parameter: table name, limit with default 10, schema with fallback to session then public, database with session default. This adds meaning beyond the schema's simple titles.
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 'Fetch a handful of rows from a table' and provides the equivalent SQL 'SELECT * FROM schema.table LIMIT n', which precisely defines the action and scope. It distinguishes itself from siblings like run_query and count_rows by focusing on raw data preview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the use case 'to see what the data actually looks like' and provides the SQL equivalent, implying it's a quick sampling tool. However, it does not explicitly state when not to use it or compare it to run_query or distinct_values.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the active PostgreSQL database and/or schema without reconnecting.
Args: database: Set the active database. Omit to leave unchanged. schema: Set the active schema. Omit to leave unchanged.
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | ||
| database | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true and destructiveHint=false, and the description does not contradict these. It adds valuable behavioral context such as 'without reconnecting' and the 'omit to leave unchanged' semantics, which go beyond the annotations by explaining how the tool behaves when parameters are omitted.
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 highly concise: a single purposeful opening sentence followed by a compact list of parameter explanations. Every sentence adds value with no filler, making it easy for an agent to parse quickly.
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?
For a simple tool with two optional parameters and read-only annotations, the description is fully complete. It explains the action, parameter semantics, and the key behavioral nuance (no reconnect). The presence of an output schema further reduces the need to describe return values.
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%, but the description fully compensates by explaining each parameter: 'database: Set the active database. Omit to leave unchanged.' and similarly for schema. This adds clear meaning beyond the raw schema properties, which only provide type and default.
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: 'Update the active PostgreSQL database and/or schema without reconnecting.' The verb 'update' combined with the specific resource ('active PostgreSQL database and/or schema') precisely conveys the action, and it distinguishes itself from sibling tools like show_context or clear_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it modifies the active database/schema without requiring a reconnect. This implies when to use this tool (when needing to switch context) but does not explicitly mention alternatives or exclusion criteria, so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the current PostgreSQL session context: connected server, database and schema.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds value by specifying exactly what is shown (server, database, schema) but does not provide additional behavioral context such as error conditions or authentication requirements. This is similar to the get_calls calibration example, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the verb and resource. Every word earns its place, and it provides enough detail without any fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema present, the description fully covers what the agent needs to know to invoke it. It specifies the exact information returned (server, database, schema), and the presence of an output schema means return values need not be described in the tool description.
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 tool accepts zero parameters, so parameter semantics are trivially satisfied. Per the rubric, a baseline of 4 is given for 0 params, and the description adds no unnecessary param information. It could not add more meaning beyond the empty 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 uses a specific verb ('Show') and clearly identifies the resource ('current PostgreSQL session context') with its components (server, database, schema). This clearly distinguishes it from sibling tools like list_databases or list_tables, which list available resources rather than showing the current session's context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to display the current session context. It does not explicitly state when not to use it or mention alternatives, but for a simple read-only introspection tool, the intended usage is clear from the description alone.
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. Dates show when Glama detected each change.
v0.1.0check_authclear_contextconnect_servercount_rowsdescribe_tabledistinct_valueslist_databaseslist_postgres_serverslist_schemaslist_tablesrun_querysample_rowsset_contextshow_contextEach tool targets a distinct resource/action: Azure server listing, connection management, session context, and per-table operations (describe, sample, count, distinct). No two tools overlap in purpose, and the read-only query tool is clearly separated from specialized row/count/distinct tools.
Nearly all tools follow a consistent verb_noun snake_case pattern (list_tables, connect_server, run_query, set_context). The one exception is 'distinct_values', which uses an adjective_noun form instead of a verb-based name, creating a slight deviation from the otherwise uniform pattern.
14 tools is well within the ideal 3–15 range and each one serves a clear, non-redundant purpose for interacting with Azure Database for PostgreSQL. The count feels appropriately scoped—comprehensive without bloat.
The tool set fully covers the lifecycle of connecting, exploring, and querying a PostgreSQL database: discover servers, connect, list databases/schemas/tables, inspect table schemas, sample data, count rows, get distinct values, and run read-only SQL. No obvious gaps for the domain of read-only database inspection.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Official Microsoft MCP Server to query Microsoft Entra data using natural language
Read-only PostgreSQL, MySQL, SQL Server access via MCP — 24 dialect-aware hosted tools.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ChingEnLin/SQMCPaL'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
