MCP Client Onboarding

hs-sql-agent exposes a Streamable HTTP MCP endpoint at /mcp. For the packaged Admin experience, the normal onboarding path is to let hs-sql-agent generate the client configuration for you.

Recommended onboarding flow

1. Issue the MCP key

   Open Runtime → MCP Keys, create a key for the target database, and select the minimum tools and tables the client needs.

2. Use the one-time Save and connect dialog

   Immediately after Issue Key, hs-sql-agent shows the plaintext secret and generated client configurations. This is the only time that plaintext value is available from the Admin UI.

3. Choose the client and copy its config

   Select Claude Desktop, Cursor, Visual Studio Code, or Generic HTTP, then click the corresponding Copy … config button. The copied JSON already contains the MCP endpoint and X-MCP-Server-Key header.

4. Paste, connect, then verify DML if needed

   Paste the copied JSON into the MCP client’s configuration and connect. If the key can invoke DML, test both form Elicitation decline and accept paths before production use.

Public endpoint used by generated configuration

The client configuration is generated from the server’s public endpoint 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.

Set the production value to the URL the MCP client can actually reach, including /mcp, before issuing production keys. The Admin UI reads this value from GET /api/runtime/client-config and places it into the copied configuration.

What the dialog generates

The current Admin UI provides four configuration tabs after Issue, Rotate, or Duplicate:

• Claude Desktop — a direct HTTP mcpServers entry;
• Cursor — an HTTP mcpServers entry;
• Visual Studio Code — a servers entry;
• Generic HTTP — a Streamable HTTP connection object.

All generated variants include the configured endpoint and the one-time MCP key header. You normally do not need to manually assemble this JSON.

Manual / generic authentication reference

For a client that needs a different surrounding configuration shape, use the Generic HTTP output as the reference. At the protocol level, authentication is:

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

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