중요합니다
MCP(SQL 모델 컨텍스트 프로토콜) 서버는 미리 보기 상태이며 이 설명서와 엔진 구현이 변경 될 수 있습니다. Data API Builder 버전 1.7은 미리 보기 상태이지만 MCP 기능이 태그에 아직 포함되지 1.7.83-rc 않았기 때문에 시험판 버전을 명시적으로 사용해야 합니다(예:latest: ).
SQL MCP Server는 AI 에이전트에 6개의 DML(데이터 조작 언어) 도구를 노출합니다. 이러한 도구는 데이터베이스 작업(레코드 만들기, 읽기, 업데이트 및 삭제 및 저장 프로시저 실행)을 위한 형식화된 CRUD 표면을 제공합니다. 모든 도구는 RBAC(역할 기반 액세스 제어), 엔터티 권한 및 구성에 정의된 정책을 준수합니다.
DML 도구란?
DML(데이터 조작 언어) 도구는 레코드 만들기, 읽기, 업데이트 및 삭제와 저장 프로시저 실행 등의 데이터 작업을 처리합니다. 스키마를 수정하는 DDL(데이터 정의 언어)과 달리 DML은 기존 테이블 및 뷰의 데이터 평면에서만 작동합니다.
6개의 DML 도구는 다음과 같습니다.
-
describe_entities- 사용 가능한 엔터티 및 작업을 검색합니다. -
create_record- 새 행 삽입 -
read_records- 테이블 및 뷰 쿼리 -
update_record- 기존 행 수정 -
delete_record- 행을 제거합니다. -
execute_entity- 저장 프로시저 실행
DML 도구가 전역적으로 사용하도록 설정되고 엔터티에 대해 SQL MCP Server가 MCP 프로토콜을 통해 노출합니다. 에이전트는 데이터베이스 스키마와 직접 상호 작용하지 않으며 데이터 API 작성기 추상화 계층을 통해 작동합니다.
도구
list_tools 응답
에이전트가 호출 list_tools되면 SQL MCP Server는 다음을 반환합니다.
{
"tools": [
{ "name": "describe_entities" },
{ "name": "create_record" },
{ "name": "read_records" },
{ "name": "update_record" },
{ "name": "delete_record" },
{ "name": "execute_entity" }
]
}
엔티티_설명
현재 역할에 사용할 수 있는 엔터티를 반환합니다. 각 항목에는 필드 이름, 데이터 형식, 기본 키 및 허용되는 작업이 포함됩니다. 이 도구는 데이터베이스를 쿼리하지 않습니다. 대신 구성 파일에서 빌드된 메모리 내 구성에서 읽습니다.
{
"entities": [
{
"name": "Products",
"description": "Product catalog with pricing and inventory",
"fields": [
{
"name": "ProductId",
"type": "int",
"isKey": true,
"description": "Unique product identifier"
},
{
"name": "ProductName",
"type": "string",
"description": "Display name of the product"
},
{
"name": "Price",
"type": "decimal",
"description": "Retail price in USD"
}
],
"operations": [
"read_records",
"update_record"
]
}
]
}
비고
CRUD 및 DML 실행 도구에서 사용하는 엔터티 옵션은 describe_entities에서 직접 제공됩니다. 각 도구에 연결된 내부 의미 체계 설명은 이 2단계 흐름을 적용합니다.
create_record
테이블에 새 행을 만듭니다. 현재 역할에 대한 만들기 권한이 엔터티에 필요합니다. 이 도구는 엔터티 스키마에 대한 입력의 유효성을 검사하고, 필드 수준 권한을 적용하고, 만들기 정책을 적용하고, 생성된 레코드를 생성된 값으로 반환합니다.
레코드 읽기
테이블 또는 뷰를 쿼리합니다. 필터링, 정렬, 페이지 매김 및 필드 선택을 지원합니다. 이 도구는 구조적 매개 변수에서 결정적 SQL을 빌드하고 읽기 권한 및 필드 프로젝션을 적용하며 행 수준 보안 정책을 적용합니다.
read_records 결과는 Data API Builder의 캐싱 시스템을 사용하여 자동으로 캐시됩니다. 데이터베이스 부하를 줄이기 위해 전역적으로 또는 엔터티별로 캐시 TTL(Time-to-Live)을 구성할 수 있습니다.
기록 업데이트
기존 행을 수정합니다. 업데이트하려면 기본 키와 필드가 필요합니다. 이 도구는 기본 키가 존재하는지 확인하고, 업데이트 권한 및 정책을 적용하며, 현재 역할이 수정할 수 있는 업데이트 필드만을 업데이트합니다.
레코드 삭제
기존 행을 제거합니다. 기본 키가 필요합니다. 이 도구는 기본 키가 존재하는지 확인하고, 삭제 권한 및 정책을 적용하고, 트랜잭션 지원을 통해 안전한 삭제를 수행합니다.
경고
일부 프로덕션 시나리오에서는 모델을 광범위하게 제한하기 위해 이 도구를 전역적으로 사용하지 않도록 설정합니다.
실행_엔티티
저장 프로시저를 실행합니다. 입력 매개 변수 및 출력 결과를 지원합니다. 이 도구는 프로시저 서명에 대해 입력 매개 변수의 유효성을 검사하고, 실행 권한을 적용하고, 매개 변수를 안전하게 전달합니다.
런타임 구성
dab-config.json의 실행 섹션에서 DML 도구를 글로벌하게 구성합니다.
{
"runtime": {
"mcp": {
"enabled": true,
"path": "/mcp",
"dml-tools": {
"describe-entities": true,
"create-record": true,
"read-records": true,
"update-record": true,
"delete-record": true,
"execute-entity": true
}
}
}
}
CLI 사용
데이터 API 작성기 CLI를 사용하여 개별적으로 속성을 설정합니다.
dab configure --runtime.mcp.enabled true
dab configure --runtime.mcp.path "/mcp"
dab configure --runtime.mcp.dml-tools.describe-entities true
dab configure --runtime.mcp.dml-tools.create-record true
dab configure --runtime.mcp.dml-tools.read-records true
dab configure --runtime.mcp.dml-tools.update-record true
dab configure --runtime.mcp.dml-tools.delete-record true
dab configure --runtime.mcp.dml-tools.execute-entity true
도구 비활성화
런타임 수준에서 도구를 사용하지 않도록 설정하면 엔터티 권한 또는 역할 구성에 관계없이 에이전트에 표시되지 않습니다. 이 설정은 엄격한 운영 경계가 필요한 경우에 유용합니다.
일반적인 시나리오
- 프로덕션 환경에서 데이터 손실을 방지하기 위해 사용하지 않도록 설정
delete-record - 읽기 전용 보고 엔드포인트에 대해
create-record를 비활성화합니다. - 저장 프로시저가 사용되지 않는 경우 사용 안 함
execute-entity
도구가 전역적으로 비활성화되면 도구가 list_tools 응답에서 숨겨지고, 호출할 수 없습니다.
엔터티 설정
명시적으로 제한하지 않는 한, 엔터티는 MCP에 자동으로 참여합니다.
dml-tools MCP에서 엔터티를 제외하거나 기능을 좁힐 수 있도록 속성이 존재하지만 정상적인 사용을 위해 아무것도 설정할 필요가 없습니다.
{
"entities": {
"Products": {
"mcp": {
"dml-tools": true
}
},
"SensitiveData": {
"mcp": {
"dml-tools": false
}
}
}
}
엔터티에 대해 지정 mcp.dml-tools 하지 않으면 MCP가 전역적으로 사용되는 경우 기본값 true 으로 설정됩니다.
세분화된 컨트롤
개별 엔터티에 대해 특정 도구를 사용하지 않도록 설정할 수 있습니다.
{
"entities": {
"AuditLogs": {
"mcp": {
"dml-tools": {
"create-record": true,
"read-records": true,
"update-record": false,
"delete-record": false
}
}
}
}
}
이 구성을 사용하면 에이전트가 감사 로그를 만들고 읽을 수 있지만 수정 또는 삭제를 방지할 수 있습니다.
RBAC 통합
모든 DML 도구 작업은 역할 기반 액세스 제어 규칙을 적용합니다. 에이전트의 역할은 표시되는 엔터티, 허용되는 작업, 포함되는 필드 및 행 수준 정책이 적용되는지 여부를 결정합니다.
역할이 anonymous에서 Products에 대한 읽기 권한만 허용하는 경우:
-
describe_entities는 작업에서만read_records를 표시합니다 -
create_record,update_record및delete_record사용할 수 없음 - 스키마에는
anonymous허용된 필드만 나타납니다.
"dab-config.json에서 역할을 구성합니다."
{
"entities": {
"Products": {
"permissions": [
{
"role": "anonymous",
"actions": [
{
"action": "read",
"fields": {
"include": ["ProductId", "ProductName", "Price"],
"exclude": ["Cost"]
}
}
]
},
{
"role": "admin",
"actions": ["*"]
}
]
}
}
}