빠른 시작

필수 비밀 정보 보호 설정

Docker를 시작하거나 런타임을 등록하기 전에 서로 독립적인 무작위 32바이트 Base64 비밀 값 세 개를 설정하세요. 모든 노드가 같은 키를 사용하고 재시작 후에도 유지해야 합니다. HMAC_KEY와 JWT_KEY는 별도의 서명 비밀 값입니다. openssl rand -base64 32를 각각 세 번 실행하세요.

SecretProtection:DatabasePasswords:ActiveKeyId는 db-1, SecretProtection:DmlPayloads:ActiveKeyId는 dml-1로 설정합니다. 누락되거나 잘못되거나 재사용된 키는 시작 실패를 일으킵니다. 예제의 자리표시자는 의도적으로 유효하지 않습니다.

HsSqlAgent.Hosting은 SecretProtection을 자동 바인딩합니다. 모듈형 호스트에서는 명시적으로 바인딩해야 합니다.

hs.AddHsSqlAgentRuntime(options =>
{
    builder.Configuration.GetSection("SecretProtection").Bind(options.SecretProtection);
});

새 bootstrap MCP 키에는 Bootstrap:Databases:*:McpKeys:*:Key 값을 명시하세요. 시작 시 키를 생성하거나 로그에 기록하지 않습니다. 기존 암호화 DB 비밀번호는 다시 입력해야 합니다. 기존 배포를 변경하기 전에 업그레이드 가이드를 읽으세요.

Host를 누가 소유해야 하는지에 따라 사용 방식을 선택합니다.

독립 배포: Docker Compose

cp .env.example .env
docker compose up -d

HMAC_KEY와 JWT_KEY는 서로 다른 32 bytes 이상의 secrets로 바꾸세요. 기본 애플리케이션 Port는 8080, MCP endpoint는 /mcp입니다.

외부 MCP Client에서는 MCP_PUBLIC_ENDPOINT를 Client가 실제로 접근할 수 있는 절대 URL로 설정하고 /mcp까지 포함합니다.

완전한 제품 임베드: HsSqlAgent.Hosting

dotnet add package HsSqlAgent.Hosting

using HsSqlAgent.Hosting;

var builder = WebApplication.CreateBuilder(args);
builder.AddHsSqlAgentStandardHost();

var app = builder.Build();
app.UseHsSqlAgentStandardHost();
await app.RunAsync();

Docker와 동일한 표준 공식 Capability 구성 및 DML 승인 Provider 설정 계약을 사용합니다.

맞춤 ASP.NET Core 통합: HsSqlAgent.Server

HsSqlAgent.Server를 설치하고 AddHsSqlAgentCore()를 호출한 뒤 Runtime, Admin Store/API, MCP, Identity, Telemetry, 승인 Capability 중 필요한 것만 명시적으로 추가합니다. ASP.NET Core 통합을 참고하세요.

MCP Key 발급

Admin UI에서 MCP Key를 만들고 하나의 관리 대상 Database에 연결한 뒤 Client가 필요한 Tools와 Tables만 공개합니다. 생성된 Client 설정을 사용하거나 Streamable HTTP endpoint에 X-MCP-Server-Key를 보냅니다.

DML 승인

기본 공식 승인 방식은 MCP Elicitation입니다. 표준 Hosting은 설정으로 공식 Webhook adapter를 선택할 수 있고, 맞춤 Server Host는 HsSqlAgent.Approvals.Webhook 또는 자체 IDmlApprovalProvider를 등록할 수 있습니다.

별도 batch DML Tool은 필요하지 않습니다. 기존 execute_dml_sql이 세미콜론으로 구분한 하나 이상의 지원 DML을 받아 승인 후 하나의 Transaction으로 원자적으로 commit합니다.