Methodify.SqlMcp 0.4.0


                    
dotnet tool install --global Methodify.SqlMcp --version 0.4.0
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Methodify.SqlMcp --version 0.4.0
                    
This package contains a .NET tool you can call from the shell/command line.
#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 dnx command.
  • 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:

  1. The workspace parameter, or FABRIC_WORKSPACE when omitted. Any workspace you can access is reachable unless an allowlist is set.
  2. The database parameter; 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_data rejects 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 database parameter.
  • 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 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.4.0 141 10/8/2026
0.3.0 151 9/2/2026
0.2.0 125 9/2/2026
0.1.0 134 8/28/2026