hs-sql-agent exposes database tools over MCP. The authenticated key determines the user database, allowed tools, table whitelist, and per-key request quota.

Executes one SELECT statement.

The parser supports joins, nested conditions, grouping, ordering, limits/offsets, CTEs, subqueries, set operations, window functions, scalar/aggregate functions, CASE, and arithmetic expressions.

Server policy still controls the maximum returned rows and timeout. A missing or larger requested limit cannot exceed QueryMaxRows.

Returns column names, types, nullability, and semantic descriptions.

Lists tables available to the key, including semantic descriptions when configured. The table whitelist is applied.

Lists database schemas. It takes no caller-provided parameters.

Updates table and column descriptions used by schema discovery. Availability depends on the key's allowed tools.

Executes one INSERT, UPDATE, or DELETE through MCP Elicitation.

McpServer and CancellationToken are injected by the MCP framework and are not caller arguments.

1. Parse and validate the DML and table access.
2. Enforce the UPDATE/DELETE WHERE policy.
3. Execute inside a transaction.
4. Reject and roll back if affected rows exceed DmlMaxAffectedRows.
5. Roll back the dry run and obtain the affected-row count.
6. Call McpServer.ElicitAsync() so the MCP client prompts the human user.
7. Commit only after the human explicitly accepts.
8. Record result, affected rows, approval status, duration, and any error category.

An AI agent cannot supply a confirmation token or make a second tool call to bypass Elicitation. A policy denial cannot be overridden by approval. If the client does not advertise Elicitation support, the server refuses to execute the change.

Human approval prompt — the client shows the SQL target and dry-run affected-row count before submission.

Custom tools are created in the Admin Panel and injected into eligible MCP sessions. They are useful for predictable or domain-specific operations because the AI client supplies only declared parameters instead of generating full SQL.

Custom query tools enforce table access, maximum rows, timeout, and SQL concurrency. Custom DML tools additionally enforce DML guardrails and the same human Elicitation workflow.

A custom tool named get_customer_orders can define a query with customerId, status, and limit parameters. The AI client invokes it with:

{
  "customerId": 42,
  "status": "shipped",
  "limit": 10
}

The database structure stays administrator-controlled while the caller provides only values.

• Tool discovery returns only tools allowed by the key.
• Table access is checked for nested queries and DML definitions.
• Inherit keys use runtime security-policy request defaults.
• Custom keys use their own request count/window.
• Unlimited disables only the authenticated-key quota; all other safeguards remain active.
• Expired or revoked keys fail authentication.
• Editing or immediately rotating/revoking a key invalidates cached authorization.

AI client
  -> tools/list or tools/call
  -> authenticate MCP key
  -> filter tools and database scope
  -> acquire request and SQL limits
  -> parse and validate definition
  -> compile dialect-specific SQL
  -> query, or DML dry-run + Elicitation
  -> write structured audit event
  -> return result

See Admin Panel for key and custom-tool management.