MCP 키는 /mcp 요청을 인증하고 hs-sql-agent가 사용하는 런타임 authorization scope를 전달합니다. Admin 사용자 세션이나 OIDC ID와는 별개의 경계입니다.
공식 2.0.2 내장 도구 표면
키 관리 서비스가 인식하는 내장 도구는 다섯 개입니다.
| Tool | 범위 |
|---|---|
get_schemas | schema discovery |
get_tables | table discovery |
get_columns | column discovery |
execute_query_sql | 통제된 SELECT 실행 |
execute_dml_sql | 통제된 Safe DML |
같은 데이터베이스에 게시된 Custom Tool도 이름으로 선택할 수 있습니다. 자세한 내용은 Custom Tools를 참고하십시오.
키 발급
- 이름 지정
요청에는 빈 값이 아닌 이름이 필요하며 최대 100자입니다.
- 데이터베이스 바인딩
2.0.2 발급 validator는 DbManagementId를 필수로 요구합니다.
- 도구 선택
내장 도구와 해당 데이터베이스에 게시된 Custom Tool을 선택합니다.
- 데이터 접근 제한
클라이언트가 바인딩된 데이터베이스의 일부만 봐야 한다면 table whitelist를 활성화합니다.
- 수명 주기 제어
필요한 경우 만료, CORS origin, rate-limit mode/override를 설정합니다.
- 평문 secret 복사
대화상자를 닫기 전에 새 키를 클라이언트 secret store에 저장합니다.
발급 필드
| 필드 | 의미 |
|---|---|
Name | 운영자에게 표시되는 키 이름 |
ExpiresAt | 선택적 만료 시각. 설정 시 미래 시각이어야 함 |
AllowedTools | 쉼표로 구분한 tool 이름. 빈 값은 제한 없음 |
CorsAllowedOrigins | 브라우저에서 시작하는 MCP 요청에 대한 선택적 origin 제한 |
DbManagementId | 바인딩된 데이터베이스 항목. 발급 시 필수 |
TableWhitelist | 선택적 qualified-table allowlist |
RateLimitMode | Inherit, Custom, Unlimited |
PermitLimitOverride | 키별 custom rate limiting에 사용 |
WindowSecondsOverride | 키별 custom rate limiting에 사용 |
저장된 key record는 식별용 짧은 prefix만 노출합니다. 원본 secret은 서버 HMAC secret으로 검증되며 이후 다시 표시하기 위한 형태로 보관하지 않습니다.
키 교체
Rotation은 기존 키의 데이터베이스/도구/테이블/CORS/rate-limit scope를 복사한 대체 키를 만듭니다.
운영자는 0~1440분의 grace period를 선택할 수 있습니다.
0이면 기존 키를 즉시 폐기합니다.- 양수이면 필요한 경우 기존 키의 만료 시각을 grace-period deadline으로 앞당깁니다.
- 대체 키에는 새로 생성된 평문 secret이 발급됩니다.
키 복제
Clone은 런타임 scope를 복사하되 새로운 이름과 secret을 가진 독립 키를 만듭니다. 동일한 권한이 필요하지만 하나의 credential을 공유하면 안 되는 두 클라이언트에 유용합니다.
복제된 키는 독립적인 수명 주기를 가지므로 원본 키에 영향을 주지 않고 폐기하거나 교체할 수 있습니다.
키 폐기
Revocation은 키를 비활성 상태로 표시하고, 변경이 commit되기 전에 validation-cache 경로에 revocation tombstone을 기록합니다. 이는 최근 폐기된 credential이 stale cache를 통해 계속 검증되는 상황을 막기 위한 설계입니다.
Bootstrap 관리 키는 일반 수명 주기 메서드로 편집·교체·폐기할 수 없으며 bootstrap 설정이 해당 키의 수명 주기를 소유합니다.
Rate-limit 동작
키는 런타임 key rate-limit policy를 상속하거나 custom override를 설정하거나 명시적으로 unlimited로 둘 수 있습니다. Admin 목록 화면은 현재 보안 정책과 키 mode를 결합한 effective rate limit도 보여 줍니다.
여러 인스턴스를 운영하면서 제한을 노드 간에 함께 계산해야 한다면 distributed rate-limiter 설정을 사용하십시오.
DML과 Elicitation
execute_dml_sql을 선택하면 클라이언트 호환성 요구 사항이 달라집니다. MCP 클라이언트는 interactive mutation approval에 사용되는 form Elicitation 흐름을 지원해야 합니다.
새 클라이언트에 DML 권한을 주기 전에 MCP 클라이언트 온보딩을 확인하십시오.