Skip to main content

How to embed the StackQL MCP server in a .NET application

StackQL's MCP server can run inside a .NET application with no separate install and no runtime dependency. The StackQL.Mcp package spawns the signed StackQL binary over stdio behind the official C# MCP SDK client, so a worker service or agent gets a governed, self-describing SQL interface to every cloud and SaaS provider in the StackQL registry. This is the pattern behind driftwatch, a scheduled drift-check worker service.

Steps​

  1. Add the package:
dotnet add package StackQL.Mcp

An optional StackQL.Mcp.AgentFramework package adds Agent Framework integration. Requires .NET 8 or later (the packages multi-target net8.0 and net9.0).

  1. Start the server and call a tool. The builder defaults to StackqlMode.ReadOnly:
using StackQL.Mcp;

await using var server = await StackqlMcp.CreateBuilder()
    .WithMode(StackqlMode.ReadOnly)
    .WithAuth("github", "null_auth")
    .StartAsync();

var tools = await server.ListToolsAsync();
var result = await server.CallToolAsync("list_services",
    new() { ["provider"] = "github", ["row_limit"] = 5 });

The builder also exposes .WithBinary(), .WithBundlePath(), .WithApproot(), and .WithCommand().

  1. Choose a mode. .WithMode() defaults to StackqlMode.ReadOnly. Set StackqlMode.Safe, StackqlMode.DeleteSafe, or StackqlMode.FullAccess only when the app needs to provision. Escalation is explicit.

Ship a self-contained executable​

Two ways to source the binary:

  • Sidecar (default) - the platform bundle is downloaded on first run, sha256-verified, cached at ~/.stackql/mcp-server-bin/<version>/<platform-key>/, and spawned over stdio.
  • Vendored - embed the bundle as a build resource:
dotnet build -p:StackqlVendorBundle=/path/to/stackql-mcp-windows-x64.mcpb

Override the binary or bundle at runtime with the STACKQL_MCP_BIN or STACKQL_MCP_BUNDLE environment variables.

Demo app​

driftwatch is a .NET Worker Service that embeds the read-only StackQL server and, on a schedule, runs a suite of SQL drift checks (public exposure, missing tags or licenses, baseline drift) and posts the findings to a Teams Adaptive Card.