hs-sql-agent
C# SQL Agent MCP服务器，支持原始SQL输入、严格AST验证，并内置管理界面。消除六大数据库中的LLM幻觉与安全风险。
文档
hs-sql-agent
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.
Why hs-sql-agent?
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.
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 Panel at http://localhost:8080. Configuration options and production deployment guidance are documented in the Wiki.
Use with an MCP client
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.
NuGet for existing .NET APIs
Embed the MCP SQL Agent and optional Admin UI in an ASP.NET Core application:
dotnet add package HsSqlAgent.Server
builder.Services.AddHsSqlAgent(options => { ... });
app.UseHsSqlAgent(); // API only
// app.UseHsSqlAgent().ServeAdminUi(); // API and Admin UI
See the NuGet Package guide for configuration and deployment details.
How SQL execution works
- 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.
Documentation
| 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 |
SQL Execution Flow
DML Approval Prompt
This is what the human-in-the-loop approval step looks like during execute_dml_sql:
Contributing
See CONTRIBUTING.md and the Development guide.