Database Management는 이후 MCP 키에 바인딩할 수 있는 데이터베이스 연결을 관리하는 Admin 제어 평면 영역입니다. 데이터베이스 항목에는 provider와 연결 메타데이터가 저장되며, MCP 클라이언트가 요청 시 임의의 connection string을 전달하지 않습니다.
지원 provider
2.0.2은 공통 SQL provider runtime을 통해 다음 provider identifier를 지원합니다.
- PostgreSQL
- MySQL
- SQL Server
- Oracle
- SQLite
- Firebird
설정된 provider는 Query 및 DML 실행 시 사용할 SQL dialect와 capability profile도 결정합니다.
연결 필드
2.0.2 데이터베이스 요청 모델에는 다음 필드가 있습니다.
| 필드 | 용도 |
|---|---|
Name | 운영자에게 표시되는 연결 이름 |
SqlProvider | 데이터베이스 provider/dialect |
Host | 데이터베이스 host 또는 provider별 위치 |
Port | 문자열 형식의 provider port |
Username | 데이터베이스 로그인 사용자 |
Password | 데이터베이스 비밀번호. SQLite만 선택 사항 |
Database | provider connection-string factory가 사용하는 database/catalog/file 값 |
ExtraSettings | 선택적 provider-specific connection settings |
CreatedBy와 UpdatedBy도 service request model에 있지만 MCP 클라이언트가 제어하는 필드가 아니라 제어 평면 메타데이터입니다.
연결 생성
Runtime → Database Management에서 다음 순서로 진행합니다.
- 데이터베이스 항목을 만들고 운영자가 구분하기 쉬운 이름을 지정합니다.
- provider를 선택합니다.
- provider별 연결 필드를 입력합니다.
- hs-sql-agent에 실제 필요한 권한만 가진 전용 데이터베이스 계정을 사용합니다.
- 항목을 저장한 뒤 운영 MCP 키에 연결하기 전에 접속 상태를 확인합니다.
API는 빈 이름을 거부합니다. SQLite를 제외한 모든 provider는 비밀번호가 없으면 backend validation에서 거부됩니다.
연결 테스트
Admin runtime은 연결 테스트 작업을 제공합니다. 기존 Database Management 항목을 테스트하면 서버가 저장된 연결 정보를 불러오고, 저장된 비밀번호를 복호화하고, provider connection string을 다시 만든 뒤 해당 provider의 connection test를 수행합니다.
연결 테스트가 실패했다면 MCP SQL 동작을 디버깅하기 전에 연결/설정 문제부터 해결해야 합니다.
일반적인 원인은 다음과 같습니다.
- hs-sql-agent 프로세스에서 host 또는 port에 도달할 수 없음
- database/catalog 이름 오류
- 잘못된 자격 증명
ExtraSettings에 필요한 TLS/encryption 설정 누락- 데이터베이스 방화벽 또는 네트워크 정책
- provider별 인증 요구 사항
메타데이터 탐색
/runtime/db-management에 대한 view 권한이 있으면 Admin API에서 저장된 연결의 provider metadata를 조회할 수 있습니다.
- schema 목록
- 특정 schema의 table 목록
- 특정 table의 column 목록
이 작업들은 저장된 데이터베이스 항목에서 provider connection을 구성합니다. MCP schema discovery와는 별개이며, MCP 경로에서는 인증된 MCP 키의 table whitelist와 semantic enrichment도 적용됩니다.
MCP 키 바인딩
운영 환경용 MCP 키는 Database Management 항목을 참조해야 합니다. 해당 연결이 그 키의 데이터베이스 경계가 됩니다.
MCP 키에서는 추가로 다음 범위를 더 좁힐 수 있습니다.
- tool allowlist
- table whitelist
- CORS origin
- 만료 시각
- rate-limit mode/override
자세한 내용은 MCP 키를 참고하십시오.
Table whitelist는 데이터베이스 항목에 저장되지 않습니다
Database Management는 연결을 정의합니다. 테이블 권한 부여는 MCP 키에 적용됩니다.
따라서 여러 MCP 키가 하나의 실제 데이터베이스 연결을 공유하면서 서로 다른 table/tool scope를 가질 수 있습니다. 예를 들어 한 키는 리포팅 테이블의 읽기만 허용하고, 다른 운영 워크플로용 키는 다른 테이블과 DML을 노출할 수 있습니다.
Semantic metadata는 데이터베이스 모델에 속합니다
테이블/컬럼 표시 이름, 설명, 동의어, 관계, 지표는 Database Management 항목에 연결됩니다. Schema discovery는 물리 데이터베이스 schema를 바꾸지 않고 MCP에 보이는 metadata를 보강할 수 있습니다.
자세한 내용은 Semantic Metadata를 참고하십시오.
권한
2.0.2 Admin API는 Database Management 작업에 명시적인 권한을 적용합니다.
| 작업 | 권한 |
|---|---|
| 연결 및 metadata 목록/조회 | /runtime/db-management → view |
| 생성 | /runtime/db-management → create |
| 수정 | /runtime/db-management → edit |
| 삭제 | /runtime/db-management → delete |
| semantic metadata 조회 | /runtime/db-management/semantic → view |
| semantic metadata 수정 | /runtime/db-management/semantic → edit |
따라서 Admin 사용자가 로그인되어 있다는 사실만으로는 충분하지 않으며 작업별 authorization이 추가로 확인됩니다.
운영 지침
Database Management 항목에는 안정적인 이름을 사용하고, 활성 MCP 키가 참조 중인 연결의 의미를 임의로 바꾸지 마십시오. 키를 다른 데이터베이스 경계로 옮겨야 한다면 명시적인 키 수명 주기 작업으로 처리하고 table/tool scope를 다시 검증하는 편이 안전합니다.
데이터베이스 자격 증명과 provider-specific secret은 secret으로 취급하십시오. Custom Tool 템플릿이나 클라이언트 설정에 넣지 말고, 클라이언트에는 MCP endpoint와 MCP key만 전달해야 합니다.