hs-sql-agent

Turn trusted SQL into governed MCP tools for AI agents.

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.