MCP 클라이언트 연결

hs-sql-agent는 /mcp에 Streamable HTTP MCP 엔드포인트를 제공합니다.

클라이언트 연결

1. MCP 키 발급

   관리자 화면에서 접속할 데이터베이스에 연결된 키를 만듭니다. 클라이언트에 전체 권한이 필요하지 않다면 사용할 수 있는 도구와 테이블을 최소한으로 제한하세요.

2. 공개 MCP 엔드포인트 사용

   클라이언트에서 실제로 접근할 수 있는 URL을 사용합니다. 관리자 UI와 MCP 엔드포인트가 같은 호스트나 포트를 사용한다고 가정하지 마세요.

3. 모든 요청 인증

   아래 MCP 요청 헤더로 키를 전송합니다. 평문 키는 비밀값으로 다뤄야 합니다. 발급·갱신 대화상자를 닫으면 같은 값은 다시 표시되지 않습니다.

4. 실제로 사용할 클라이언트 확인

   먼저 스키마 조회와 쿼리 실행을 확인합니다. DML을 활성화할 예정이라면 운영 환경에 배포하기 전에 form Elicitation 동작도 별도로 테스트하세요.

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

공개 엔드포인트

운영자 화면과 자동 생성되는 클라이언트 설정에 표시되는 URL은 다음 서버 설정에서 가져옵니다.

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

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

자동 생성되는 클라이언트 설정

MCP 키를 발급, 교체 또는 복제하면 관리자 화면에서 Claude Desktop, Cursor, 일반 Streamable HTTP 클라이언트용 직접 연결 설정을 생성할 수 있습니다.

평문 키는 일시적으로만 표시됩니다. 발급·갱신 대화상자를 닫은 뒤에는 서버가 같은 비밀값을 다시 보여 줄 수 없습니다.

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

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

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

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

다음 문서