This server lets an MCP AI agent manage many SQL Server instances from one entry point, grouped in a hot-reloaded connections file, with read-only safety rails and DBA-oriented analysis tools.
List all configured SQL Server connections, grouped by client/environment.
Reload connections from connections.json without restarting the agent.
Run SQL queries with row caps (default 1000, max 10000), cancellation on overflow, CSV format option, and server messages/statistics.
Fetch table schema: columns, types, nullability, defaults.
Fetch index information: types, key columns, included columns.
Get execution plans via SHOWPLAN_XML without running the query.
Retrieve stored procedure source code.
Every response includes metadata identifying which connection answered.
Enforce per-connection readOnly guards that reject writing statements before execution.
Support environment-variable password references and inline JSON config for credential security.
Check connectivity across all connections at once with --check.
Support NTLM domain auth and Entra ID / Azure AD authentication options.
One MCP entry, every SQL Server you administer. Connections live in a single
connections.json, grouped by client or environment, hot-reloaded without
restarting your AI agent — plus execution plans, index audits and
stored-procedure analysis.
Built for DBAs and consultants, not for a demo against a single localhost database.
Add this to your AI agent's MCP configuration:
{
"mcpServers": {
"sqlserver": {
"command": "npx",
"args": ["-y", "@cevelas/mcp-sqlserver"]
}
}
}Then create your connections file and restart the agent:
npx -y @cevelas/mcp-sqlserver --initThat writes ~/.mcp-sqlserver/connections.json from a commented template. Edit
it, and ask your agent to "list all SQL Server connections".
Agent | Config file |
Claude Desktop (Windows) |
|
Claude Desktop (macOS) |
|
Claude Code |
|
VS Code / Copilot |
|
Cursor |
|
Any MCP-compatible agent works — ChatGPT, Gemini, Copilot, Cline, Zed and
others all take the same command / args pair.
Related MCP server: MySQL MCP Server
Most SQL Server MCP servers take a single connection string. That is fine for one database. It falls apart when you administer thirty across eight clients, because every instance needs its own entry in the agent config, its own credentials, and its own restart when something changes.
Single-DSN servers | This one | |
Instances per MCP entry | 1 | all of them |
Organised by client or environment | — |
|
Add or change a connection | edit agent config, restart | edit a file, |
Which server answered? | you assume | in every response's |
Beyond | — | execution plans, index layout, SP source |
Read-only safety rail | — |
|
{
"connections": [
{
"name": "acme-prod",
"connectionGroup": "Acme Corp",
"description": "Production - head office",
"server": "192.168.1.10\\SQLEXPRESS",
"database": "AcmeDB_Prod",
"user": "app_reader",
"password": "${env:ACME_PROD_PASSWORD}",
"port": 1433,
"encrypt": true,
"trustServerCertificate": false,
"readOnly": true
}
]
}Field | Required | Notes |
| yes | Unique; this is what you say to the agent |
| yes | Hostname, IP, or |
| no | Client, project or environment. Groups the listing |
| no | Shown in |
| no | Defaults to the login's default database |
| no | Omit for domain or Entra ID auth |
| no | Defaults to 1433 |
| no |
|
| no | Rejects writing statements — see below |
Anything else you put here is passed straight to mssql,
so requestTimeout, connectionTimeout, pool, authentication and a nested
options object all work.
Any string may reference an environment variable:
"password": "${env:ACME_PROD_PASSWORD}"A connection that references a variable you have not set is disabled, and
list_connections names both the connection and the missing variable. Leaving
the literal in place would only move the failure to connect time, where it
arrives as Login failed for user and tells you nothing.
You can also skip the file entirely and pass the whole thing through the agent config, which keeps credentials in one place with the rest of your MCP secrets:
{
"mcpServers": {
"sqlserver": {
"command": "npx",
"args": ["-y", "@cevelas/mcp-sqlserver"],
"env": {
"MSSQL_MCP_CONNECTIONS_JSON": "{\"connections\":[{\"name\":\"prod\",\"server\":\"10.0.0.1\",\"database\":\"App\",\"user\":\"reader\",\"password\":\"...\"}]}"
}
}
}
}In order, first hit wins:
--connections <path>
$MSSQL_MCP_CONNECTIONS — a path
$MSSQL_MCP_CONNECTIONS_JSON — the JSON itself, inline
./connections.json in the working directory
~/.mcp-sqlserver/connections.json
connections.json next to the installed package
A path given explicitly via 1 or 2 that does not exist is an error — the server will not quietly fall back to a different file and talk to the wrong database.
npx -y @cevelas/mcp-sqlserver --checkConnects to every entry in parallel, runs SELECT 1, and lists which ones
fail and why. Exits non-zero if any did, so it works in a scheduled task.
Useful after a password rotation, or before blaming the agent.
The bundled tedious driver supports NTLM and the Entra ID (Azure AD) family.
Add domain for NTLM:
{
"name": "warehouse",
"server": "dwh.corp.local",
"database": "DWH",
"domain": "CORP",
"user": "svc_analytics",
"password": "${env:DWH_PASSWORD}"
}{
"name": "azure-sql",
"server": "myserver.database.windows.net",
"database": "reporting",
"encrypt": true,
"authentication": {
"type": "azure-active-directory-password",
"options": { "userName": "${env:AZURE_USER}", "password": "${env:AZURE_PASSWORD}" }
}
}Fully integrated auth — a trusted connection with no password at all — needs
the native msnodesqlv8 driver, which is not bundled because it would break
the one-line install on machines without a build toolchain. NTLM with an
explicit service account is the supported path.
Tool | Arguments | What it does |
| — | Every connection, grouped |
| — | Re-read the file, drop open pools |
|
| Run a query |
|
| Columns, types, nullability, defaults |
|
| Indexes, types, key and included columns |
|
|
|
|
| Source of a stored procedure |
Every response carries the connection it came from:
{
"metadata": {
"connection": "acme-prod",
"connectionGroup": "Acme Corp",
"description": "Production - head office",
"server": "192.168.1.10\\SQLEXPRESS",
"database": "AcmeDB_Prod"
},
"data": [ ... ]
}With thirty connections in play, that line is what tells you the answer came from the client you meant.
An agent that runs SELECT * FROM Orders does not need four million rows, and
neither does its context window.
Row cap. query returns at most 1000 rows across all result sets.
maxRows changes that, up to 10000. When the cap is hit the query is
cancelled on the server, not trimmed afterwards.
A truncated result says so, first. The response opens with
"truncated": true and a note stating that more rows exist, that the total
is unknown, and how to get it. It sits before the rows on purpose: a
10000-row response runs to hundreds of KB, and a client that cuts long output
keeps the beginning. An agent must never conclude "the table has 10000 rows"
from a capped result. Asking for more than 10000 is not an error — the cap is
lowered to 10000, and if rows were left out the note says what was asked for.
format: "csv". JSON repeats every column name on every row. With
csv the response is one JSON header line with the metadata, a blank line,
then the rows. NULL is an empty cell and an empty string is "", so the
two stay distinguishable.
Server messages. PRINT output and SET STATISTICS IO, TIME ON results
come back in messages, so the agent can read logical reads and CPU time
instead of guessing.
Every result set. A batch with several SELECTs returns them all in
recordsets. data is still the first one.
Binary columns come back as hex (0x8f3a...), truncated after 64 bytes,
instead of a JSON array with one number per byte.
rowCount is always present; truncated, messages and recordsets only
appear when they have something to say. Responses are compact JSON.
Things that are tedious by hand and become one sentence to the agent:
"Why is this stored procedure slow?" — get_stored_procedure for the
source, get_execution_plan for the plan, get_indexes for what is missing.
"Compare the Orders schema between acme-prod and acme-qa" — get_schema on
both, agent diffs them.
"Which indexes on this table are never covering anything?" — get_indexes
plus the queries you care about.
"I added a client to connections.json" — reload_connections, no restart.
"readOnly": trueRejects INSERT, UPDATE, DELETE, MERGE, DROP, TRUNCATE, ALTER,
CREATE, GRANT, EXEC, BACKUP, DBCC, OPENQUERY, DISABLE/ENABLE
and friends before the query leaves your machine. It also requires the batch to
start with something that reads — SELECT, WITH, DECLARE, SET, IF
and so on — because T-SQL lets you call a procedure without EXEC, and
sp_rename 'dbo.Users','Users_old' contains no blocked keyword at all.
String literals, comments and bracketed identifiers are ignored, so
WHERE note = 'please delete this', SELECT [delete] FROM [Audit] and
DECLARE @Create DATETIME all pass. get_execution_plan still works, because
SHOWPLAN_XML returns the plan without executing anything.
Anything other than an explicit false turns the guard on — a hand-written
"readOnly": "false" locks the connection down rather than silently opening
it, and says so in list_connections.
This is a guard rail, not a security boundary. It stops an agent from
"helpfully" fixing a row in production. It will not stop someone determined to
write. The real protection is a SQL login that only has db_datareader:
CREATE LOGIN mcp_reader WITH PASSWORD = '...';
CREATE USER mcp_reader FOR LOGIN mcp_reader;
ALTER ROLE db_datareader ADD MEMBER mcp_reader;
GRANT VIEW DEFINITION TO mcp_reader; -- for get_stored_procedure
GRANT SHOWPLAN TO mcp_reader; -- for get_execution_planUse both.
connections.json holds credentials. Keep it out of version control — the
bundled .gitignore covers connections*.json.
Prefer ${env:VAR} over literal passwords.
Give each connection the least privilege it needs. Do not use sa.
Restrict file permissions:
icacls connections.json /inheritance:r /grant:r "%USERNAME%:F" on Windows,
chmod 600 connections.json elsewhere.
The query tool runs whatever SQL the agent writes. That is the point of the
tool — treat the connection's permissions as the boundary, not the tool.
web/connections.html is a standalone page for editing connections.json
without hand-writing JSON: drag and drop between groups, duplicate a
connection, autocompleting group selector, and auto-save through the File
System Access API in Chrome and Edge. No build, no dependencies, entirely
optional. See web/README.md.
Grab the .mcpb bundle from the
latest release
and drag it onto Claude Desktop's extensions settings. It will ask for the path
to your connections.json and wire everything up.
Your existing connections.json works unchanged — every new field is optional
and the tools take the same arguments. Two things worth knowing:
Multi-connection was broken before 3.0. The server used the mssql
global connection pool, which ignores the config it is handed once a
connection is already open. In practice every connection after the first
silently reused the first one's server and database. If you were relying on
results from more than one connection in a session, they may not have come
from where you thought. Fixed in 3.0 with a pool per connection.
If your agent config points at node C:\path\to\index.js, that still works.
The file resolution order now checks that path last, so nothing moves.
npm install
npm test # unit tests, no database needed
node .github/scripts/smoke.mjs # packs, installs and speaks MCP to the tarballAgainst a real server, name a connection from your own file:
MSSQL_TEST_CONNECTION=local npm run test:integrationThe mssql driver is injected, so the unit tests mock only that boundary —
everything else is the real code path. test/contract.test.js freezes the tool
names and arguments so a refactor cannot change the MCP surface by accident.
MIT — see LICENSE.
Christian Velasquez — @cvelasquez
Get execution plan for a query
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to analyze | |
| connection | Yes | Connection name to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already covers the read-only nature. The description adds no extra behavioral context such as whether the query is actually executed, permission requirements, or return behavior. It does not contradict the annotation, but it offers no additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler or redundant phrases. Every word contributes to the 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?
There is no output schema, yet the description is extremely sparse. It does not explain what an execution plan contains, how the result is presented, or how this tool differs from running a query. An agent must infer critical details from the tool name and siblings, which is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both sql and connection already clearly documented. The description's 'query' loosely maps to the sql parameter but adds no new meaning beyond what the schema provides.
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 'Get execution plan for a query' uses a specific verb and resource, clearly identifying what the tool does. It is distinct from siblings like query (executes) and get_schema, so an agent can select it correctly.
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 no guidance on when to use this tool versus alternatives such as query, and does not clarify that this tool analyzes rather than executes the query. There are no exclusions or conditions to help route the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get index information for a table
| Name | Required | Description | Default |
|---|---|---|---|
| table | Yes | Table name | |
| connection | Yes | Connection name to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true covers the safety profile, and the word 'Get' aligns with read-only behavior. The description adds no additional behavioral context, such as return format, execution impact, or authentication needs. Since annotations already declare the read-only nature, this is acceptable but not enhanced.
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 extremely short and front-loaded, with no redundant words. It efficiently conveys the primary action and resource. However, it is arguably too terse, leaving some context to the schema and annotations, but it is not verbose or structurally flawed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description could clarify what 'index information' includes (e.g., names, types, columns). It also does not mention any constraints like table existence or connection requirements. For a simple read-only tool, it is minimally adequate but leaves several details implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters ('table' and 'connection'). The description adds no extra meaning about parameter formats, required values, or how parameters interact. Baseline 3 applies because the schema handles the parameter 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 states a specific verb ('Get') and resource ('index information for a table'), making the core purpose clear. However, it does not differentiate this from siblings like get_schema or get_execution_plan, which could also relate to table metadata. The scope is understandable but not explicitly distinguished.
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?
There is no guidance on when to use this tool versus the sibling tools. The description does not mention alternatives, prerequisites, or conditions for use. An agent selecting from the sibling list would have to infer when get_indexes is the appropriate choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get database schema information for specific tables
| Name | Required | Description | Default |
|---|---|---|---|
| table | No | Table name (optional, returns all if not specified) | |
| connection | Yes | Connection name to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds no additional behavioral context beyond the basic action. It doesn't describe return format, scope semantics (e.g., all tables when omitted), or any side effects. With no extra behavioral disclosure, the description adds nothing beyond what annotations already convey.
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 focused sentence with no filler; it front-loads the verb and resource. Every word contributes to identifying the tool's purpose. Nothing extraneous is present.
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 read-only tool with two well-documented parameters and no output schema, the description is largely sufficient. It could be improved by noting that the table parameter is optional (though the schema already says this) and by mentioning what kind of schema information is returned. Overall, an agent can correctly identify and invoke the tool with the provided information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter descriptions already explain table (optional) and connection (required). The description adds no extra meaning to either parameter, such as expected formats or special values. Baseline 3 is appropriate since the schema carries the burden.
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 ('Get'), a concrete resource ('database schema information'), and identifies the target ('specific tables'). This distinguishes it from siblings like query, get_indexes, and get_stored_procedure at a glance. However, it doesn't explicitly differentiate from close siblings or mention that omitting the table returns all tables, which is a minor clarity gap.
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 no guidance about when to choose this tool over alternatives such as query, get_indexes, or get_stored_procedure. There is no explicit when/when-not, and the existence of closely related sibling tools makes this absence noticeable. Usage context must be inferred entirely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get stored procedure definition
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Stored procedure name | |
| connection | Yes | Connection name to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation, and the description adds no further behavioral context. It does not describe what 'definition' includes, whether it returns SQL text, what happens if the procedure does not exist, or any permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, with no filler or redundant phrasing. It front-loads the core purpose effectively, though it could be expanded slightly without losing its concise character.
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 two-parameter read-only tool, the definition is minimally viable: the parameters are fully documented and the readOnlyHint covers safety. However, with no output schema and no return-value description, the agent is left guessing about the exact shape or content of the returned definition.
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 already provides full descriptions for both required parameters (name and connection), so the description does not need to repeat them. It also adds no extra meaning beyond the schema, which is why the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: it retrieves the stored procedure definition. It is unambiguous about which object it targets and is distinguishable from siblings like get_schema or get_indexes, though it does not explicitly contrast itself with them.
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 no guidance on when to use this tool versus alternatives such as query or get_execution_plan. There is no mention of prerequisites, exclusions, or typical scenarios, so the agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available SQL Server connections grouped by connectionGroup
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes that this is a safe read operation, and the description aligns with that by using the word 'List'. The description adds some behavioral detail about grouping, but it does not disclose whether connections are live-tested, cached, or what the exact output shape looks like. Given the annotation covers the main safety concern, a score of 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, front-loaded sentence with no filler. It states the action, the resource, and the grouping behavior efficiently, giving the agent exactly what it needs to understand the tool.
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 zero-parameter listing tool with a readOnly annotation, the description is largely complete. It does not explain the exact return fields or format, but 'List all available SQL Server connections grouped by connectionGroup' gives sufficient functional context for an 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 tool has zero parameters, so the description does not need to document parameter meanings. The input schema is empty and the description adds no unnecessary parameter details, keeping this dimension at the baseline for no-parameter tools.
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 ('List') and identifies the exact resource ('all available SQL Server connections') and result structure ('grouped by connectionGroup'). It clearly distinguishes this tool from the query-focused sibling tools like query and get_schema.
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 makes its purpose obvious: it is the discovery/listing tool for connections rather than a tool that executes queries or inspects schemas. It does not explicitly state alternatives or exclusions, but for a zero-parameter list operation, the intended 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.
Execute a SQL query on the database
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | SQL query to execute | |
| format | No | Output format (default json). csv is far more compact for wide or long results: the first line is a JSON header with metadata, then the rows as CSV. | |
| maxRows | No | Maximum rows to return across all result sets (default 1000, max 10000). When the cap is hit the query is cancelled on the server and the response starts with truncated: true. A truncated result is incomplete and the total row count is unknown: never report the cap as the number of rows. Prefer TOP, WHERE or aggregates over raising this. | |
| connection | Yes | Connection name to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden, but it only says 'Execute a SQL query on the database.' It does not disclose that executing SQL may modify data, require permissions, cancel when row limits are hit, or return multiple result sets. The schema does include maxRows cancellation details, but that is structured field information, not behavior disclosed by the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, which is concise. However, it is so minimal that it provides little structural benefit; it front-loads a generic action but omits any useful qualifiers or context. It is not a well-structured information-bearing description.
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 tool that executes arbitrary SQL and has no output schema, the description is incomplete. It does not mention connection requirements, supported formats, row limits, cancellation behavior, or whether the tool can perform writes. The schema fills some gaps, but the overall description leaves an agent without enough context to invoke the tool confidently and interpret its behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description itself adds no parameter-level meaning beyond what the schema already provides for connection, sql, format, and maxRows. It does not enrich or clarify any parameter 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 states a specific verb and resource: 'Execute a SQL query on the database.' This clearly identifies the tool's function and distinguishes it from the sibling metadata tools like get_schema and get_indexes. However, it does not explicitly address whether arbitrary read/write SQL is allowed, so it is clear but not fully differentiated in terms of scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to use this tool instead of siblings such as get_schema, get_execution_plan, or list_connections, nor does it mention prerequisites like needing an existing connection. The intended selection logic is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reload connections from connections.json file without restarting the MCP server. Closes existing connection pools and loads new configuration.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals a meaningful side effect beyond annotations: it 'closes existing connection pools and loads new configuration', which warns the agent that active pooled connections will be torn down. It does not contradict the idempotent/non-destructive hints and adds useful operational context, though failure-mode behavior is left undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences contain no filler: the first states the action and its benefit, the second states the side effect. All information is front-loaded and earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter administrative reload, the description is nearly complete: it identifies the trigger, the source file, and the main side effect. There is no output schema and no mention of validation/error behavior if the file is invalid, which an agent might need to anticipate, but the core call is clear.
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 no parameters and the schema reflects that fully, so the baseline of 4 applies. The description doesn't need to document any parameters; the only relevant details are the source file and reload behavior, both covered.
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 names a specific verb ('reload') and resource ('connections.json') and clearly distinguishes this administrative action from read-only sibling tools like list_connections or query. It also states the operational benefit ('without restarting the MCP server'), so the agent knows exactly what action this tool performs.
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 'without restarting the MCP server' implies the intended use case: applying connection configuration changes at runtime. It does not explicitly name an alternative or state when not to use it, but siblings are mostly query/read tools, and the distinction is reasonably inferable.
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.
v3.1.0query2 fields changedInput schema / properties / formatAdded value: +{
+ "description": "Output format (default json). csv is far more compact for wide or long results: the first line is a JSON header with metadata, then the rows as CSV.",
+ "enum": [
+ "json",
+ "csv"
+ ],
+ "type": "string"
+}Input schema / properties / maxRowsAdded value: +{
+ "description": "Maximum rows to return across all result sets (default 1000, max 10000). When the cap is hit the query is cancelled on the server and the response starts with truncated: true. A truncated result is incomplete and the total row count is unknown: never report the cap as the number of rows. Prefer TOP, WHERE or aggregates over raising this.",
+ "maximum": 10000,
+ "minimum": 1,
+ "type": "integer"
+}v3.0.0get_execution_planget_indexesget_schemaget_stored_procedurelist_connectionsqueryreload_connectionsScored across 7 tools
Each tool serves a distinct purpose: query executes SQL, get_schema retrieves table schemas, get_indexes gets index info, get_execution_plan analyzes query plans, get_stored_procedure fetches procedure definitions, list_connections enumerates connections, and reload_connections refreshes configuration. No overlap or ambiguity.
Tool names follow a consistent verb_noun pattern: get_* for retrieval of specific metadata, list_ for enumeration, reload_ for refreshing, and query as a direct verb. All names are snake_case and predictable.
7 tools is well within the ideal 3-15 range for a SQL Server MCP server. Each tool addresses a core need (querying, schema inspection, performance analysis, connection management) without redundancy.
The surface covers query execution and common metadata operations (schema, indexes, execution plans, stored procedures) plus connection management. Minor gap: no direct 'list tables' or 'list databases' tool, but these can be obtained via query, so it's a workable gap.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Generate, fix, explain and run read-only SQL on PostgreSQL, MySQL and SQL Server
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
DBRE-grade SQL analysis inside any MCP client. No connection. No install. Paste a query.
