A high-performance MCP server for secure SQL access and enterprise governance.
hs-sql-agent connects MCP clients to SQLite, PostgreSQL, MySQL, SQL Server, Oracle, and Firebird through an HTTP MCP endpoint and a built-in Admin Panel.
Instead of executing unrestricted LLM-generated SQL, the server parses supported SQL into structured definitions, validates it, and rebuilds the final statement through a provider-specific SQL compiler.
- Six database providers — SQLite, PostgreSQL, MySQL, SQL Server, Oracle, and Firebird.
- Governed access — Per-key database binding, table whitelisting, CORS, rate limits, and execution policies.
- Safe DML — Transactional dry-run followed by MCP Elicitation for explicit human approval.
- Admin Panel — Manage databases, keys, roles, custom tools, audit records, and runtime policies.
- Enterprise ready — OIDC SSO, TOTP MFA, audit retention, Prometheus metrics, OTLP, and webhook/SIEM delivery.
- Semantic metadata — Table and column synonyms, relationships, and scoped metric metadata for schema discovery.
SQL support is intentionally bounded: unsupported syntax is rejected instead of silently changing its meaning. See the MCP Tools Reference for the supported SQL 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 Panel at http://localhost:8080. Configuration options and production deployment guidance are documented in the Wiki.
Create an MCP key in the Admin Panel. The key dialog displays the plaintext secret once and generates configuration for Claude Desktop, Cursor, and generic Streamable HTTP clients.
Set MCP_PUBLIC_ENDPOINT to the externally reachable MCP URL, including /mcp. For client compatibility, onboarding, and DML Elicitation requirements, see MCP client onboarding.
Embed the MCP SQL Agent and optional Admin UI in an ASP.NET Core application:
dotnet add package HsSqlAgent.Serverbuilder.Services.AddHsSqlAgent(options => { ... });
app.UseHsSqlAgent(); // API only
// app.UseHsSqlAgent().ServeAdminUi(); // API and Admin UISee the NuGet Package guide for configuration and deployment details.
- Authenticate the MCP key and apply its database, table, and policy scope.
- Parse supported SQL into a structured definition.
- Validate the definition and compile it for the configured database provider.
- Execute queries within configured limits.
- For DML, dry-run in a transaction and require human approval through MCP Elicitation before commit.
Custom SQL tools pass through the same parser, validation, access policy, and execution limits as built-in tools. Lifecycle, parameter, and publishing rules are documented in the Admin Panel guide.
| Topic | Documentation |
|---|---|
| Getting started | Getting Started |
| Configuration | Configuration |
| Admin Panel | Admin Panel |
| MCP tools and SQL support | MCP Tools Reference |
| Security, OIDC, and MFA | Security Governance |
| Deployment and observability | Deployment · Distributed Deployment |
| API | API Reference |
| Troubleshooting | Troubleshooting |
| Development | Development |
This is what the human-in-the-loop approval step looks like during execute_dml_sql:
See CONTRIBUTING.md and the Development guide.