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.

ExecuteSQL is the write entry point for all DDL and DML operations against the connected SQL Server or Azure SQL Database. It is marked destructive in MCP metadata (ReadOnly=false, Idempotent=false, Destructive=true) — MCP-aware agents and clients should confirm intent with the user before calling it.
SELECT is rejected by design. Any query that reads rows — including plain SELECT, CTEs that resolve to a SELECT, sys.* catalog queries, INFORMATION_SCHEMA queries, and DMVs — must use ReadData instead. If a SELECT is detected, ExecuteSQL returns an error:
“ExecuteSQL does not allow SELECT or other read-only queries. Use ReadData for all SELECT statements, including sys.*, INFORMATION_SCHEMA, and DMVs.”

​
Parameter

​
sql
string
required
A single non-SELECT T-SQL statement (DDL or DML). Multi-batch scripts separated by GO are not supported. A trailing semicolon is allowed; a semicolon between two statements is rejected.

​
Accepted statement types

ExecuteSQL accepts any statement whose leading keyword is one of the following:
CategoryKeywords
DMLINSERT, UPDATE, DELETE, MERGE
DDLCREATE, ALTER, DROP, TRUNCATE
ProceduralEXEC, EXECUTE
SecurityGRANT, REVOKE, DENY
BackupBACKUP, RESTORE

​
Rejected inputs

  • SELECT — use ReadData.
  • WITH … SELECT (read-only CTEs) — use ReadData.
  • Multi-statement batches containing an internal semicolon (e.g. INSERT …; UPDATE …).
  • GO batch separators.
The SqlStatementClassifier enforces this split. An unsupported leading keyword produces:
“Unsupported or unrecognized statement type ‘{keyword}’. Use ReadData for SELECT queries.”

​
AI Insights integration

On every successful execution, the server calls QueueInsightDdlProcessing(), which enqueues a background DDL audit drain and schema-fingerprint reconciliation via InsightDdlProcessingQueue. This happens automatically whenever USE_INSIGHTS_LAYER is enabled (the default). No extra configuration is required. When the DDL backlog is processed, any cached SchemaInsights rows whose fingerprint no longer matches the live object are archived to AIInsights.InsightHistory. If INSIGHTS_AUTOPOPULATE is also enabled, mechanical baseline insights are rebuilt for affected objects.

​
Return value

ExecuteSQL returns a DbOperationResult object: 
{
  "success": true,
  "error": null,
  "rowsAffected": 1
}
rowsAffected is populated for DML statements. For DDL statements it reflects the value returned by ExecuteNonQuery (typically –1 or 0).

​
Examples

​
CREATE TABLE

CREATE TABLE dbo.Orders (
    OrderId   INT           NOT NULL IDENTITY(1,1) PRIMARY KEY,
    CustomerId INT          NOT NULL,
    OrderDate  DATETIME2(0) NOT NULL DEFAULT SYSUTCDATETIME(),
    TotalAmount DECIMAL(18,2) NOT NULL
);

​
ALTER TABLE — add a column

ALTER TABLE dbo.Orders
ADD ShippedDate DATETIME2(0) NULL;

​
DROP TABLE with IF EXISTS guard

DROP TABLE IF EXISTS dbo.Orders;

​
DELETE with a WHERE clause

DELETE FROM dbo.Orders
WHERE OrderDate < '2020-01-01';

​
EXEC a stored procedure

EXEC dbo.usp_ProcessDailyOrders @RunDate = '2024-06-01';
Prefer the typed tools — CreateTable, DropTable, InsertData, and UpdateData — when you need only one of those specific operations. They surface clearer MCP metadata intent and make agent audit logs easier to read.

Build docs developers (and LLMs) love

Get started for freeTalk to us