MCP 클라이언트 연결

hs-sql-agent는 /mcp에 Streamable HTTP MCP 엔드포인트를 제공합니다. 내장 관리자 화면을 사용하는 경우 endpoint와 header를 직접 조합하는 방식이 기본 흐름이 아닙니다. 키를 발급한 뒤 hs-sql-agent가 생성한 설정을 그대로 MCP 클라이언트에 붙여 넣으면 됩니다.

권장 연결 절차

1. MCP 키 발급

   Runtime → MCP Keys에서 대상 데이터베이스용 키를 만들고 클라이언트에 필요한 도구와 테이블만 선택합니다.

2. 한 번만 표시되는 Save and connect 사용

   Issue Key가 성공하면 hs-sql-agent가 평문 키와 생성된 클라이언트 설정을 즉시 보여 줍니다. 관리자 화면에서 이 평문 값을 확인할 수 있는 유일한 시점입니다.

3. 클라이언트를 선택하고 설정 복사

   Claude Desktop, Cursor, Visual Studio Code, Generic HTTP 중 하나를 선택한 뒤 해당 Copy … config 버튼을 누릅니다. 복사되는 JSON에는 MCP endpoint와 X-MCP-Server-Key가 이미 포함되어 있습니다.

4. 붙여 넣고 연결한 뒤 필요하면 DML 검증

   복사한 JSON을 MCP 클라이언트 설정에 붙여 넣고 연결합니다. DML을 사용할 경우 운영 배포 전에 form Elicitation의 거절과 승인 흐름을 모두 확인하세요.

생성 설정에 사용되는 공개 엔드포인트

클라이언트 설정의 URL은 다음 서버 설정에서 가져옵니다.

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

같은 값을 환경 변수로 지정할 때는 Mcp__PublicEndpoint를 사용합니다. 제공되는 Compose 구성은 MCP_PUBLIC_ENDPOINT 값을 이 설정으로 전달합니다.

운영용 MCP 키를 발급하기 전에, 실제 클라이언트에서 접근할 수 있고 /mcp를 포함하는 URL로 설정하세요. 관리자 화면은 GET /api/runtime/client-config에서 이 값을 읽어 복사되는 설정에 그대로 넣습니다.

대화상자가 생성하는 설정

Issue, Rotate, Duplicate가 성공하면 현재 관리자 화면은 다음 네 가지 설정을 제공합니다.

• Claude Desktop — 직접 HTTP 연결용 mcpServers 항목
• Cursor — HTTP mcpServers 항목
• Visual Studio Code — servers 항목
• Generic HTTP — Streamable HTTP 연결 객체

모든 형식에 서버에 설정된 endpoint와 이번에 생성된 MCP 키가 들어갑니다. 일반적으로 JSON을 직접 조합할 필요가 없습니다.

Generic / 수동 인증 참고

클라이언트에서 다른 외부 설정 형식이 필요하다면 Generic HTTP 출력을 기준으로 사용하세요. 프로토콜 수준 인증은 다음 header입니다.

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

DML 지원 여부는 별도로 확인해야 합니다

/mcp에 정상적으로 연결되었다고 해서 DML 승인까지 지원한다는 뜻은 아닙니다.

execute_dml_sql과 공개된 DML Custom Tools에는 form Elicitation이 필요합니다. 운영 환경에서 DML을 허용하기 전에 실제 설치한 클라이언트 버전으로 다음 두 경로를 모두 확인하세요.

1. Elicitation 요청을 거절하고 데이터 변경이 커밋되지 않는지 확인합니다.
2. Elicitation 요청을 승인하고 승인한 데이터 변경만 완료되는지 확인합니다.

다음 문서