Methodify.SqlMcp
0.4.0
dotnet tool install --global Methodify.SqlMcp --version 0.4.0
dotnet new tool-manifest
dotnet tool install --local Methodify.SqlMcp --version 0.4.0
#tool dotnet:?package=Methodify.SqlMcp&version=0.4.0
nuke :add-package Methodify.SqlMcp --version 0.4.0
Methodify.SqlMcp
A Model Context Protocol (MCP) server that lets an AI agent explore and query Microsoft SQL Server, Azure SQL, and Microsoft Fabric warehouses and lakehouses.
It is built for schema exploration and analysis: pointing an agent at a real database so it can answer questions from real data, check a design against what is actually deployed, or map out an unfamiliar schema. The server runs read-only by default, bounds what a query can return, and on Fabric can find its own way from a workspace name to a SQL endpoint.
Tools
Every tool takes an optional database parameter, and in workspace mode an optional workspace
parameter. When you omit them, the tool uses the defaults from configuration, so one server
instance can explore every database and workspace the login can reach. The two Fabric tools,
list_workspaces and refresh_sql_endpoint, are registered only in workspace mode.
The four list_* tools take an optional pattern, a SQL LIKE pattern on the object name such
as %SAVEDVIEW% or Cust%. On a catalog with thousands of objects, pass one rather than reading
the whole list.
Every call is checked against the tool's schema before it runs. An argument the tool does not
have, or a missing required one, returns Success: false naming the problem, the valid
arguments, and the likely intended name — for example describe_table has no argument named 'table_name'. ... Did you mean 'table_name' -> 'name'? — instead of the argument being silently
dropped or the call failing with a generic message.
Available by default (read-only)
| Tool | Description |
|---|---|
list_workspaces |
Lists the Fabric workspaces this session can query. Workspace mode only. |
refresh_sql_endpoint |
Syncs a lakehouse or mirrored database's SQL endpoint with OneLake and reports per-table status. Workspace mode only. |
list_databases |
Lists databases. In workspace mode, includes each one's item type, id, and OneLake path. |
list_tables |
Lists base tables, optionally filtered by a LIKE pattern. |
describe_table |
Returns columns, indexes, constraints, and foreign keys; in workspace mode, the OneLake path too. |
list_views |
Lists views, optionally filtered by a LIKE pattern. |
describe_view |
Returns a view's definition and columns. |
list_stored_procedures |
Lists user-defined stored procedures, optionally filtered by a LIKE pattern. |
describe_stored_procedure |
Returns a procedure's definition and parameters. |
list_functions |
Lists scalar, table-valued, and CLR functions, optionally filtered by a LIKE pattern. |
describe_function |
Returns a function's definition, parameters, and return type. |
read_data |
Runs a SELECT query and returns the rows, within the result guards, with the row cap pushed into the query as TOP where that is safe. |
Available only when you enable writes
| Tool | Description |
|---|---|
create_table |
Runs a CREATE TABLE statement. |
drop_table |
Runs a DROP TABLE statement. |
insert_data |
Runs an INSERT statement. |
update_data |
Runs an UPDATE statement. |
Requirements
- The .NET 10 SDK or later, which provides the
dnxcommand. - For workspace mode, a signed-in Azure identity, such as from
az login.
Configure your MCP client
There are two ways to tell the server where to connect. Set exactly one.
With a connection string
{
"mcpServers": {
"sql": {
"type": "stdio",
"command": "dnx",
"args": ["Methodify.SqlMcp", "--yes"],
"env": {
"CONNECTION_STRING": "Server=.;Database=test;Trusted_Connection=True;TrustServerCertificate=True"
}
}
}
}
With a Fabric workspace
{
"mcpServers": {
"sql": {
"type": "stdio",
"command": "dnx",
"args": ["Methodify.SqlMcp", "--yes"],
"env": {
"FABRIC_WORKSPACE": "Data warehouse",
"FABRIC_DATABASE": "gold"
}
}
}
}
dnx downloads the package on first run and caches it, so there is nothing to clone or build.
To pin a version, add it to the arguments: ["Methodify.SqlMcp", "--version", "0.4.0", "--yes"].
Connection-string mode
The server reads its connection string from CONNECTION_STRING and connects exactly as told.
Local SQL Server:
Server=.;Database=test;Trusted_Connection=True;TrustServerCertificate=True
Azure SQL Database with Microsoft Entra ID:
Server=tcp:<server>.database.windows.net,1433;Initial Catalog=<database>;Encrypt=Mandatory;Authentication=Active Directory Default
Microsoft Fabric, by endpoint:
Server=<workspace>.datawarehouse.fabric.microsoft.com;Database=<lakehouse or warehouse>;Authentication=ActiveDirectoryDefault
Authentication=ActiveDirectoryDefault uses DefaultAzureCredential, so it picks up the identity
you already have from the Azure CLI, Visual Studio, or a managed identity. If a connection times
out with a "Task canceled" error, try Active Directory Interactive instead.
In this mode the workspace parameter is refused with a message that explains workspace mode,
and the Fabric tools are not registered.
Workspace mode
Set FABRIC_WORKSPACE to a workspace display name or id instead of looking up its host. The
server calls the Fabric REST API with your delegated identity, finds the workspace's SQL
analytics host, and connects with Authentication=ActiveDirectoryDefault and certificate
validation on. Nothing is stored; there is no service principal.
| Variable | Meaning |
|---|---|
FABRIC_WORKSPACE |
Workspace display name or id. Names match exactly, ignoring case. Required. |
FABRIC_DATABASE |
Default database: a lakehouse, warehouse, or SQL endpoint display name. Required when the workspace has more than one. |
FABRIC_WORKSPACE_ALLOWLIST |
Semicolon-separated names or ids the workspace parameter may name. FABRIC_WORKSPACE is always allowed. |
SQL_MCP_REFRESH_TIMEOUT |
Seconds refresh_sql_endpoint waits for the service. Default 300; 0 means no limit. |
How a tool call finds its target:
- The
workspaceparameter, orFABRIC_WORKSPACEwhen omitted. Any workspace you can access is reachable unless an allowlist is set. - The
databaseparameter; then, in the default workspace only,FABRIC_DATABASE; then, if the workspace has exactly one database, that one. A workspace with several databases and nothing named returns an error that lists them. Silently picking one would send different runs to different databases.
Resolution happens in the background after startup, so the client's handshake is never delayed, and answers are cached for the life of the process. Watch stderr to see the resolved host.
In workspace mode list_databases comes from the Fabric API rather than sys.databases, and
reports what the SQL host actually exposes: every warehouse, plus every SQL analytics endpoint,
each joined to the lakehouse, mirrored database, or Fabric SQL database behind it. Each entry
carries type, id, sqlEndpointId, oneLakeTablesPath, defaultSchema, and
provisioningStatus. describe_table adds an oneLake block with the table's https and
abfss paths, including the schema folder when the item is schema-enabled.
list_workspaces returns only workspaces on a Fabric-capable capacity. Workspaces with no
capacity are Power BI Pro workspaces; per-user, embedded, and EM SKUs do not run Fabric workloads.
A workspace whose capacity SKU is not visible to you is included rather than hidden.
Refreshing a SQL endpoint
A lakehouse's SQL analytics endpoint learns about tables written by Spark through a metadata
sync that can lag the write by minutes. refresh_sql_endpoint(database?, workspace?, tables?)
asks the endpoint to sync now and returns one status record per table with its
lastSuccessfulSyncDateTime. Pass tables — as table or schema.table, up to 25 — to sync
only those, which is faster than a full refresh. A status of NotRun means the endpoint found no
changes for that table; it was already current. Warehouses maintain their own metadata and are
refused. The call needs a contributor role on the workspace, waits up to
SQL_MCP_REFRESH_TIMEOUT seconds, and does not modify data or schema.
Result guards
read_data bounds what a query can return, so one SELECT * on a fact table cannot flood the
model's context or hang the session. When a guard fires the result says so: Truncated is true,
RowsReturned counts what came back, and Notice names the guard and how to change it. Nothing
is dropped silently.
| Variable | Default | Effect |
|---|---|---|
SQL_MCP_MAX_ROWS |
200 | Stop after this many rows. Per call, limit overrides it. |
SQL_MCP_MAX_BYTES |
65536 | Stop once the serialized rows pass roughly this size. The row that crosses the line is kept. |
SQL_MCP_MAX_STRING_LENGTH |
1000 | Cut longer string values with a marker, trim trailing char(n) padding, and replace binary values with a size note. Per call, max_string_length overrides it. |
SQL_MCP_COMMAND_TIMEOUT |
60 | Seconds before any command, in any tool, is abandoned. |
For every guard, 0 means off. read_data(max_string_length: 0) returns values exactly as
stored: no truncation, no padding trim, binary as base64.
The row cap is pushed into the query. Stopping the reader after 200 rows bounds memory but
not time: the Fabric SQL analytics endpoint computes the whole result before the first row
streams, so an unbounded SELECT * on a large table runs to completion server-side however few
rows are read. Measured on a tenant: 71 s for SELECT * FROM dim_product against under 5 s with
TOP. So when a row cap applies, read_data inserts TOP (cap + 1) after the outer SELECT
— or after SELECT DISTINCT — whenever that cannot change the query's meaning: a single
SELECT, optionally with a WITH clause, with exactly one SELECT at the top level, no TOP
already, and no OFFSET … FETCH. TOP honors the query's own ORDER BY. A query with UNION,
INTERSECT, or EXCEPT at the top level is sent unchanged, because TOP there would limit only
the first branch; the reader stop applies instead. The query is never wrapped in an outer
subquery. Rewritten SQL is logged at debug level.
Read-only by default
The server registers only the read tools unless you opt in to writes. When the write tools are
not registered they never appear in the client's tool list, so the model has no way to call them.
read_data also rejects anything that is not a single SELECT or WITH statement, including
SELECT ... INTO, stacked statements, batch separators, and extended stored procedures.
To enable the tools that modify the database, set SQL_MCP_ALLOW_WRITES:
"env": {
"CONNECTION_STRING": "...",
"SQL_MCP_ALLOW_WRITES": "true"
}
MSSQL_MCP_ALLOW_WRITES, the name in 0.1.0, still works and logs a deprecation.
These checks are convenience, not a security boundary. They keep a well-behaved agent from wandering into a destructive statement by accident. They are not designed to stop a determined attempt to get around them, and a model that can write arbitrary SQL is a broad capability whatever the server does with it.
The control that actually holds is the identity in your connection string or az login. For
read-only use, connect as a login that only has read permissions:
CREATE USER [mcp_reader] FROM LOGIN [mcp_reader];
ALTER ROLE db_datareader ADD MEMBER [mcp_reader];
Grant no more than the agent's task needs, and treat any database reachable through this server as readable by whatever model is on the other end.
Build from source
git clone https://github.com/methodify/sql-mcp.git
cd sql-mcp
dotnet build
To run the tests:
dotnet test
The unit tests need no database; the Fabric layer is tested against canned API responses. The
integration tests run against a live server and are skipped unless CONNECTION_STRING is set.
They create uniquely named tables and drop them afterward, so point them at a scratch database
rather than anything you care about.
To run the server from a source checkout, replace the dnx command in your MCP configuration:
"command": "dotnet",
"args": ["run", "--project", "/path/to/sql-mcp/src/Methodify.SqlMcp/Methodify.SqlMcp.csproj"]
Origins
This project began as the MssqlMcp .NET sample from
Azure-Samples/SQL-AI-samples, which is MIT
licensed. Microsoft removed that sample from the repository on 2026-06-03 in a commit titled
"Removed unsafe MCP sample", on the grounds that it was leading people toward the wrong pattern
for building MCP servers. The concern was real: the sample handed a model a set of tools that ran
arbitrary SQL, including INSERT, UPDATE, CREATE TABLE, and DROP TABLE, with nothing in
front of them. Two upstream issues asked for a read-only mode and neither was resolved before the
sample was withdrawn.
This project keeps the parts of that sample that were useful and addresses the reason it was pulled. Compared with the original:
- Read-only by default. Write tools are registered only when you opt in, and
read_datarejects statements that are not reads. This is the change that addresses the withdrawal. - Result guards. Rows, bytes, string length, and command time are all bounded, with a notice when a bound is hit.
- Fabric workspace mode. Name a workspace and the server finds the endpoint, across every workspace you can access.
- Nine more tools. The original covered tables only. This one adds workspaces, databases, endpoint refresh, and listing and describing for views, stored procedures, and functions.
- Multi-database support. Every tool takes an optional
databaseparameter. - Packaged for
dnx. Installs from NuGet with no clone and no build step. - Runnable tests. The original test suite required a live database for every test. The unit tests here run anywhere, and the live tests are opt-in.
- Current dependencies. Targets .NET 10 and the 2.x MCP C# SDK.
This project is not affiliated with or endorsed by Microsoft.
If you want a Microsoft-supported option instead, see SQL MCP Server, which is built on Data API Builder and exposes configured entities rather than open schema access. It solves a different problem: it is a better fit for a production application, and a worse fit for open-ended exploration of a database you do not know yet.
License
MIT. See LICENSE. The original copyright notice from the Microsoft sample is retained there alongside my own.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
This package has no dependencies.