A fail-closed SQL execution and governance boundary for AI agents.
hs-sql-agent sits between AI-generated SQL and your databases. It accepts raw SQL through MCP, parses it into a structured compiler model, validates source and target capabilities, applies access and execution policy, and only then renders SQL for the target provider.
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.
- 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 → executablecompiler 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.
cp .env.example .env
# Set HMAC_KEY and JWT_KEY to unique secrets of at least 32 bytes.
docker compose up -dOpen the Admin UI at http://localhost:8080.
For production settings and deployment options, use the Configuration Reference and Deployment Guide.
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.
For the same batteries-included composition as the official Docker host, install HsSqlAgent.Hosting:
dotnet add package HsSqlAgent.Hostingusing 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.
- Authenticate the MCP key and establish its database, table, and execution-policy scope.
- Parse SQL into the closed compiler model and bind source semantics.
- Normalize and validate syntax, semantics, capabilities, and policy.
- Render only an executable typestate into provider-specific SQL and parameters.
- 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.
The documentation site is the source of truth for detailed configuration, integration, SQL capability, security, and operations guidance:
See CONTRIBUTING.md and the Architecture and Contribution Flow.