hs-sql-agent

Turn trusted SQL into governed MCP tools for AI agents.

<img width="1000" height="500" alt="coverImage" src="https://github.com/user-attachments/assets/e317cee2-7bf3-4b11-94b9-4fdeedb29689" />

hs-sql-agent is an open-source SQL-to-MCP tool factory and governed SQL execution boundary. Define parameterized SQL in the Admin UI, publish it as a typed MCP tool, and let AI agents supply only the arguments — without writing a new C# method or redeploying your MCP server for every database operation.

Every published tool still runs through the same fail-closed SQL compiler, per-key database/table policy, runtime limits, audit trail, and Safe DML approval controls. Raw SQL tools remain available for cases where an agent genuinely needs flexible ad-hoc querying.

It supports PostgreSQL, MySQL, SQL Server, Oracle, SQLite, and Firebird and can run as the complete first-party server with its Admin UI or be embedded into an existing ASP.NET Core application.

Publish SQL as an MCP tool

Instead of teaching the model to regenerate the same query every time, define the SQL shape once:

SELECT id, total, status
FROM orders
WHERE customer_id = {{ customerId }}
  AND status = {{ status }}

Declare customerId and status in Runtime → Custom Tools, test the draft, then publish it. hs-sql-agent exposes the published definition to MCP clients as a named tool with a generated JSON input schema.

The agent sees a contract conceptually like:

get_customer_orders(
  customerId: number,
  status: string
)

The SQL template stays engineer-defined. Placeholders are value parameters only; identifiers and arbitrary SQL fragments cannot be injected through them.

Published custom tools can be Query or DML tools. Query tools use the same typed compiler and access-policy path as built-in SQL execution. DML tools use the same preview → approval → revalidation → commit protocol, including atomic multi-statement transactions.

Why hs-sql-agent?

• SQL-to-MCP Custom Tools — Turn engineer-reviewed SQL templates into discoverable MCP tools with typed parameters, descriptions, draft/test/publish lifecycle, revisions, rollback, and database binding.
• Fail-closed SQL compiler — Unsupported or unproven syntax is rejected instead of being silently rewritten with different semantics.
• Closed F# compiler core — SQL enters a closed discriminated-union AST and advances through unforgeable parsed → bound → canonical → validated → executable compiler stages.
• Six database providers — PostgreSQL, MySQL, SQL Server, Oracle, SQLite, and Firebird with provider-aware validation and lowering.
• Safe DML — Read-only impact preview, one-time approval challenge, commit-time row-set revalidation, and explicit human approval through MCP Elicitation or an approval provider.
• Governed access — Per-key database binding, table whitelisting, rate limits, execution limits, roles, policies, and audit records.
• Flexible hosting — Run the packaged server and Admin UI, use the standard ASP.NET Core host, or compose advanced integrations from modular capabilities.
• Production observability — Prometheus metrics, OpenTelemetry/OTLP, audit retention, and webhook/SIEM delivery.

SQL support is intentionally bounded by proven semantics. See the SQL Support Reference for the current contract.

Quick Start

cp .env.example .env
# Set HMAC_KEY and JWT_KEY to unique secrets of at least 32 bytes.
docker compose up -d

Open the Admin UI at http://localhost:8080.

For production settings and deployment options, use the Configuration Reference and Deployment Guide.

Use with an MCP client

Set MCP_PUBLIC_ENDPOINT to the externally reachable MCP URL, including /mcp, before issuing production keys.

Then open Runtime → MCP Keys in the Admin UI and issue a key. The one-time Save and connect dialog generates ready-to-paste configuration for Claude Desktop, Cursor, Visual Studio Code, and generic Streamable HTTP clients.

The plaintext secret is shown only once. See MCP Client Onboarding for client setup, compatibility, and DML Elicitation requirements.

Use from .NET

For the same batteries-included composition as the official Docker host, install HsSqlAgent.Hosting:

dotnet add package HsSqlAgent.Hosting

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();

await app.RunAsync();

Use HsSqlAgent.Server directly only when you need custom authentication, middleware ordering, approval providers, UI, or capability composition.

See the ASP.NET Core Integration Guide and the HsSqlAgent.Hosting package README for the full integration contract.

How SQL execution works

1. Authenticate the MCP key and establish its database, table, tool, and execution-policy scope.
2. For Custom Tools, resolve the published definition and render declared value parameters into the engineer-defined SQL template.
3. Parse SQL into the closed compiler model and bind source semantics.
4. Normalize and validate syntax, semantics, capabilities, and policy.
5. Render only an executable typestate into provider-specific SQL and parameters.
6. Execute within configured runtime limits.

The compiler core is provider-driver-free: parsing, validation, normalization, capability proof, lowering, and rendering are kept separate from database drivers and runtime execution.

For DML, hs-sql-agent first builds a read-only impact preview, binds approval to the validated plan and matched row set, requires explicit human approval, and revalidates inside the commit transaction before applying the mutation.

Custom SQL tools pass through the same compiler, access policy, and execution limits as built-in tools.

SQL Execution Flow

<picture> <source media="(prefers-color-scheme: dark)" srcset="miscellaneous/diagram-black.png"> <source media="(prefers-color-scheme: light)" srcset="miscellaneous/diagram-light.png"> <img alt="SQL Execution Flow" src="miscellaneous/diagram-light.png"> </picture>

DML Approval Prompt

<img width="1199" height="890" alt="dml-approval-prompt" src="https://github.com/user-attachments/assets/ebd40519-e0b3-43d6-9e83-24238f3c00d6" />

Documentation

The documentation site is the source of truth for detailed configuration, integration, SQL capability, security, and operations guidance:

• Documentation Home
• Quick Start
• Custom Tools
• ASP.NET Core Integration
• SQL Support Reference
• Security Overview

Contributing

See CONTRIBUTING.md and the Architecture and Contribution Flow.

License

Apache License 2.0