Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/A-Point-Systems-ltd/ms-sql-mcp/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the repository, building the server, wiring up your connection string, and issuing your first natural-language query to SQL Server — all in under five minutes. By the end you will have a running MCP server that your AI coding assistant can use to inspect schemas, read data, and execute write operations.

​
Prerequisites

  • .NET 9.0 SDK — download here. The SDK (not just the runtime) is required to build from source. If you use the self-contained single-file publish output, only the runtime is needed on the target machine.
  • SQL Server or Azure SQL Database — SQL Server 2008 R2 (10.50) or later, including Azure SQL Database. The server is tested against SQL Server 2008 R2 through 2022.
  • An MCP-compatible client — Cursor, VS Code with GitHub Copilot Agent, or Claude Desktop. See Clients for per-client configuration details.

​
Steps

1

Clone and build

Clone the repository and build the server project:
git clone https://github.com/A-Point-Systems-ltd/ms-sql-mcp.git
cd ms-sql-mcp\MssqlMcp
dotnet build
After a successful build, the debug executable is at:
MssqlMcp\bin\Debug\net9.0\MssqlMcp.exe
You can also run the xUnit test suite (no live database required for most tests):
cd ..
dotnet test
For a production-ready self-contained single-file binary, use the included publish script:
.\publish-release.ps1
This produces C:\Development\MCPs\MS-SQL-Release\MssqlMcp.exe by default (the output path is set in MssqlMcp/MssqlMcp.csproj).
2

Set the connection string

The server reads CONNECTION_STRING from its process environment. Do not set it as a system-wide environment variable — doing so would expose your credentials to every process on the machine. Instead, pass it only to the MCP server process via the env block of your MCP client config (see the next step).Connection string format is standard ADO.NET. A Windows authentication example:
Server=.;Database=MyDb;Trusted_Connection=True;TrustServerCertificate=True
The server validates the connection string and opens a live test connection before the MCP transport starts. A bad string causes an immediate exit (code 1) with diagnostics written to the log file.
3

Configure your MCP client

Add the server to your MCP client’s config file. The example below uses Cursor’s mcp.json format, which closely matches sample_mcp.json in the repository root:
{
  "mcpServers": {
    "MSSQL-MCP": {
      "type": "stdio",
      "command": "C:\\Development\\MCPs\\MS-SQL\\MssqlMcp\\bin\\Debug\\net9.0\\MssqlMcp.exe",
      "env": {
        "CONNECTION_STRING": "Server=.;Database=MyDb;Trusted_Connection=True;TrustServerCertificate=True",
        "USE_INSIGHTS_LAYER": "true",
        "INSIGHTS_AUTOPOPULATE": "true",
        "LOG_FILE_PATH": "C:\\Logs\\mssql-mcp.log"
      },
      "disabled": false
    }
  }
}
Replace the command path with the actual location of your built or published executable, and update CONNECTION_STRING to point at your database. See Clients / Cursor for full per-client instructions including VS Code and Claude Desktop formats.
Restart the MCP server after changing any environment variable — the server reads env vars only at startup.
4

Verify the connection

When the MCP client launches the server, startup validation runs automatically:
  1. The server checks that CONNECTION_STRING is non-empty.
  2. It opens a real ADO.NET connection to SQL Server and confirms it succeeds.
  3. Only after both checks pass does it start the MCP stdio transport and begin accepting tool calls.
If the server exits immediately (your client shows MCP error -32000: Connection closed), check the log file for details:
ScenarioLog location
LOG_FILE_PATH set to a fileThat file
LOG_FILE_PATH set to a directorymssql-mcp-<timestamp>.log inside it
Default (Windows)%LOCALAPPDATA%\MssqlMcp\Logs\mssql-mcp-<timestamp>.log
Default (Linux/macOS)~/.local/share/MssqlMcp/Logs/mssql-mcp-<timestamp>.log
The log contains the process ID, working directory, masked connection string, the SQL connection test result, and stack traces on failure.
5

Try your first prompt

Once the server is connected, open a chat in your MCP client and try:
“List tables in the database”
The agent should call the ListObjects tool with objectType=Table and return the table names from your database. From there you can ask it to describe a table, read some rows, or inspect a stored procedure.

​
First-time AI Insights workflow

The AI Insights layer caches object summaries inside the target database. It is enabled by default but must be installed once per database. When you connect to a new database, follow this sequence:
  1. GetServerInfo — confirm the server version, edition, and user database count.
  2. InsightsCheck — check whether the Insights schema, DDL audit trigger, and watermark table are present.
  3. InstallInsightsLayer — if InsightsCheck reports the schema or trigger as missing, run this tool once. The install is idempotent; re-running it is safe.
  4. ListObjects (objectType=Table) — enumerate tables; the server auto-generates mechanical baseline insights for each one when INSIGHTS_AUTOPOPULATE is enabled.
  5. DescribeTable — inspect a table and review the insight, insightFreshness, and enrichmentSuggested fields in the response.
  6. UpsertInsight — when enrichmentSuggested is true, submit the pre-filled payload from the response to upgrade the mechanical baseline to a richer, LLM-authored insight.
See AI Insights overview for the full enrichment contract (protocol MCP-Insight-Enrichment-v1).
Multi-batch GO scripts are not supported by ExecuteSQL. The tool accepts only a single T-SQL statement per call. Split multi-statement scripts at GO boundaries and issue each statement individually.

Build docs developers (and LLMs) love

Get started for freeTalk to us