내장 MCP 도구 범위는 의도적으로 작게 유지되며, 서버의 단일 정식 목록으로 강제됩니다. 공개되는 내장 도구는 다음 5개입니다.
| 도구 | 공개 입력 | 용도 |
|---|---|---|
get_schemas | 없음 | schema 탐색 |
get_tables | schemaName: string | 볼 수 있는 테이블 탐색 |
get_columns | schemaName: string, tableName: string | 볼 수 있는 컬럼과 키 메타데이터 탐색 |
execute_query_sql | sql: string | 통제된 SELECT 쿼리 한 건 실행 |
execute_dml_sql | sql: string | 승인된 DML 한 건 이상을 원자적으로 실행 |
게시된 Custom Tool은 연결된 데이터베이스의 도구 모음을 확장할 수 있지만 추가 내장 도구는 아닙니다.
서버 목록이 기준입니다
MCP 키 검증과 MCP 런타임 discovery는 같은 정식 내장 도구 이름을 사용합니다. 시작 시 hs-sql-agent는 reflection으로 발견한 MCP 메서드를 이 목록과 비교하고, 예상하지 못한 내장 도구가 추가되거나 필수 도구가 빠져 있으면 시작을 거부합니다.
Admin API의 도구 목록도 같은 내장 도구와 게시된 Custom Tool을 반환하며 Query/DML 유형과 위험 메타데이터를 함께 제공합니다. 이로써 권한 부여 경계와 Admin UI가 서로 다른 도구 목록을 따로 유지하는 문제를 방지합니다.
Semantic metadata 쓰기는 관리 작업입니다
update_semantic_layer는 hs-sql-agent의 내장 MCP 도구가 아닙니다. Semantic Layer는 제어 영역 설정이며 Admin UI 또는 권한으로 보호되는 Admin API에서 편집합니다.
읽기 전용 discovery 도구는 권한이 허용하는 범위에서 표시 이름, 설명, 동의어, 관계, 지표를 테이블과 컬럼 탐색 결과에 계속 반영합니다.
Semantic metadata를 참고하십시오.
Discovery 전에 권한을 적용합니다
MCP session은 키 인증 이후에 구성됩니다. AllowedTools를 명시하면 지정한 내장 도구와 게시된 Custom Tool만 노출됩니다. 목록이 없으면 정식 5개 내장 도구와 키에 연결된 데이터베이스의 게시된 Custom Tool을 노출할 수 있습니다.
데이터베이스 연결 범위, 테이블 allowlist, 속도 제한, SQL 동시성, 정책, 감사는 계속 서버에서 강제됩니다. 메타데이터 도구는 모델이 connection string을 전달하도록 허용하지 않습니다.
execute_query_sql
execute_query_sql(sql: string)지원되는 SELECT 한 문을 받아 parse, bind, 테이블 권한 확인, 정책 및 source semantics 검증, target capability 증명, 불변 provider command 컴파일을 거친 뒤 실행합니다.
지원하지 않는 SQL은 fail closed로 거부하며 raw provider 실행으로 우회하지 않습니다.
execute_dml_sql
execute_dml_sql(sql: string)세미콜론으로 구분한 지원 DML 한 문 이상을 받을 수 있습니다. 여러 문은 한 번만 승인되고 원래 순서대로 하나의 원자적 transaction 안에서 commit됩니다. 별도의 batch MCP 도구는 필요하지 않습니다.
| 문 | 상태 |
|---|---|
UPDATE | capability, 정책, 승인, 재검증을 모두 통과하면 지원 |
DELETE | capability, 정책, 승인, 재검증을 모두 통과하면 지원 |
INSERT ... VALUES | 변경 불가능한 payload에 묶인 승인 의미로 지원 |
INSERT ... SELECT | source row-set 승인 의미가 정의될 때까지 fail closed |
여러 문 요청은 전체 batch를 먼저 parse 및 validate하고 문별 evidence를 만든 뒤 한 번의 승인을 요청합니다. 서버가 소유한 transaction 안에서 각 문을 mutation 직전에 다시 검증하며, 모든 문이 승인된 evidence와 계속 일치할 때만 commit합니다. 하나라도 실패하면 transaction 전체를 rollback합니다.
클라이언트가 전달한 transaction-control SQL은 거부됩니다.
승인 전달 방식
MCP Elicitation은 계속 기본 승인 경로입니다. Standard Hosting은 공식 Webhook adapter를 선택할 수 있고, 모듈형 host는 HsSqlAgent.Approvals.Webhook 또는 다른 IDmlApprovalProvider를 등록할 수 있습니다.
비동기 provider는 Pending을 반환할 수 있습니다. 이후 durable completion도 서버가 소유하며 commit 전에 현재 권한, 설정, 정책, plan, row set, affected-row evidence를 다시 검증합니다.
Safe DML을 참고하십시오.