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.

The first step for any problem is to check the log file. Before the MCP transport ever starts, Program.cs writes a startup block containing the process ID, working directory, .NET version, a masked copy of the connection string, and the result of a live SQL connection test. Most failures — missing credentials, wrong server name, bad authentication — are recorded here with a FATAL: prefix and a full stack trace. If the log file exists and is empty after FATAL: lines, the process exited before the MCP handshake could begin.

​
Log file locations

ScenarioLog location
LOG_FILE_PATH set to a file pathThat exact file
LOG_FILE_PATH set to a directory pathA new mssql-mcp-{yyyy-MM-dd-HHmmss}.log inside that directory
Default (Windows)%LOCALAPPDATA%\MssqlMcp\Logs\mssql-mcp-{yyyy-MM-dd-HHmmss}.log
Default (Linux/macOS)~/.local/share/MssqlMcp/Logs/mssql-mcp-{yyyy-MM-dd-HHmmss}.log
A new timestamped file is created on each server startup, so after reproducing a failure look for the most recently modified file in the log directory.

​
Common failures

The MCP client received a transport-level close before the handshake completed. This always means the server process exited early. Open the log file and look for FATAL: lines near the top.Common root causes:
  • CONNECTION_STRING not set (process exits with code 1 immediately)
  • SQL connection test failed (bad server name, port, or credentials)
  • The executable path in the MCP client config is wrong and the process never started
After fixing the root cause, restart the MCP server from your client.
The server exits with code 1 when CONNECTION_STRING is not present in the environment. The log will contain:
FATAL: CONNECTION_STRING environment variable is not set!
Fix: add CONNECTION_STRING to the env block of your MCP client configuration and restart the server.
"env": {
  "CONNECTION_STRING": "Server=.;Database=MyDb;Trusted_Connection=True;TrustServerCertificate=True"
}
The server found a CONNECTION_STRING value but could not open a connection to SQL Server. The log will contain a FATAL: SQL Server connection test FAILED: line with the exception message and stack trace.Steps to diagnose:
  1. Copy the connection string and test it outside the MCP server using sqlcmd or SQL Server Management Studio (SSMS)
  2. Verify the server name or IP address is reachable from the machine running the MCP server
  3. Check that the database name exists
  4. For SQL logins, confirm the username and password are correct
  5. For Windows or Entra auth, confirm the account running the process has login rights on the SQL instance
  6. If TrustServerCertificate=False, ensure the SQL Server certificate is trusted or flip to True for local development
Installing the AI Insights layer creates a database-level DDL trigger (DDL_Audit), which requires elevated permissions. If the database user lacks those permissions, InstallInsightsLayer will return an error.Fix: grant the database user ALTER ANY DATABASE DDL TRIGGER, or assign the user to the ddl_admin fixed database role. If you have sysadmin access, you can also run the install as sysadmin and then downgrade the account afterward.
-- Grant fine-grained permission to a specific user
GRANT ALTER ANY DATABASE DDL TRIGGER TO [your_sql_user];
This is by design. ExecuteSQL is a write/destructive tool and the SqlStatementClassifier will reject any SELECT statement passed to it, returning a message directing you to use ReadData instead.Fix: use the ReadData tool for all queries that return rows — including queries against sys.*, INFORMATION_SCHEMA, DMVs, and user tables.
The AI Insights tools return a disabled-layer error when USE_INSIGHTS_LAYER is set to a falsey value (false, 0, no, off, or disabled).Fix: remove the USE_INSIGHTS_LAYER variable from your MCP env block (the default is enabled), or explicitly set it to true. Restart the MCP server after changing the environment variable — the flag is read once at startup.
GetServerInfo reads hardware metrics from SQL Server DMVs (dynamic management views) that require the VIEW SERVER STATE permission. When the database user lacks this permission, those fields are omitted or returned as null, and a hardware.warning field is included in the response explaining the degradation.This is expected behavior for restricted accounts. If you need hardware metrics, grant VIEW SERVER STATE to the login:
GRANT VIEW SERVER STATE TO [your_sql_login];
If you are running the development build (from dotnet build), the .NET 9.0 Runtime must be installed on the target machine. Download it from https://dotnet.microsoft.com/download/dotnet/9.0.If you used publish-release.ps1 to produce the single-file self-contained executable, the runtime is bundled inside MssqlMcp.exe and no separate .NET installation is required.

​
Diagnosing startup failures

1

Open the log file

Locate the most recently created log file using the table above. On Windows the default path is %LOCALAPPDATA%\MssqlMcp\Logs\. Open the file in any text editor.
2

Look for FATAL: lines near the top

The startup block always appears first. Any FATAL: line indicates the process exited before the MCP transport started. Read the message and exception text carefully — it usually identifies the problem directly.
3

Check the masked connection string

A few lines into the log you will see Connection String: <masked value>. Verify that the server name, database, and authentication method visible in the masked string are correct. Password fields are replaced with ***MASKED***; all other parts of the string are logged in plain text.
4

Find the SQL connection test result line

Look for either SQL Server connection test SUCCESSFUL (with server and database names) or SQL Server connection test FAILED (with exception details). A failed test always logs the full exception and stack trace — use those details to diagnose the specific connection problem.
5

If the log file does not exist

The server could not create or write to the log path. This can happen if LOG_FILE_PATH points to a directory that does not exist or to a file the process does not have write permission to create. Check the path value and the filesystem permissions, or unset LOG_FILE_PATH to fall back to the default location under %LOCALAPPDATA%.

Build docs developers (and LLMs) love

Get started for freeTalk to us