MCP Client Onboarding

hs-sql-agent exposes a Streamable HTTP MCP endpoint at /mcp.

Connect a client

1. Issue an MCP key

   Use the Admin Panel to create a key bound to the intended database. Restrict its allowed tools and tables when the client does not need unrestricted access.

2. Use the public MCP endpoint

   The endpoint must be reachable by the client. Do not assume the Admin UI origin and MCP origin are the same.

3. Authenticate every request

   Send the key with the MCP request header shown below. Treat the plaintext key as a secret; the lifecycle dialog will not display the same secret again after it is closed.

4. Verify the installed client

   Confirm schema discovery and query execution first. If DML will be enabled, test the client’s form Elicitation behavior separately before production use.

X-MCP-Server-Key: <MCP key>

Public endpoint

The URL shown to operators and generated client configurations comes from the server setting:

{
  "Mcp": {
    "PublicEndpoint": "https://sql-agent.example.com/mcp"
  }
}

The equivalent environment variable is Mcp__PublicEndpoint; the provided Compose configuration maps MCP_PUBLIC_ENDPOINT to it.

Generated client configuration

The Admin Panel generates direct HTTP configuration for Claude Desktop, Cursor, and generic Streamable HTTP clients immediately after an MCP key is issued, rotated, or duplicated.

The plaintext key is intentionally transient. Once the lifecycle dialog is closed, the server cannot display that same secret again.

DML compatibility is a separate check

A client successfully connecting to /mcp does not prove that it supports DML approval.

execute_dml_sql and published DML Custom Tools require form Elicitation. Before allowing DML in production, test the exact installed client version and verify both paths:

1. Decline an elicitation request and confirm the mutation is not committed.
2. Accept an elicitation request and confirm the approved mutation completes.

Next steps