SQL MCP Server의 DML(데이터 조작 언어) 도구

MCP(SQL 모델 컨텍스트 프로토콜) 서버는 AI 에이전트에 7개의 DML(데이터 조작 언어) 도구를 노출합니다. 이러한 도구는 데이터베이스 작업(레코드 만들기, 읽기, 업데이트 및 삭제, 데이터 집계 및 저장 프로시저 실행)을 위한 형식화된 CRUD 표면을 제공합니다. 모든 도구는 RBAC(역할 기반 액세스 제어), 엔터티 권한 및 구성에 정의된 정책을 준수합니다.

DML 도구란?

DML(데이터 조작 언어) 도구는 레코드 만들기, 읽기, 업데이트 및 삭제, 데이터 집계 및 저장 프로시저 실행과 같은 데이터 작업을 처리합니다. 스키마를 수정하는 DDL(데이터 정의 언어)과 달리 DML은 기존 테이블 및 뷰의 데이터 평면에서만 작동합니다.

7가지 DML 도구는 다음과 같습니다.

• describe_entities - 사용 가능한 엔터티 및 작업을 검색합니다.
• create_record - 새 행 삽입
• read_records - 테이블 및 뷰 쿼리
• update_record - 기존 행 수정
• delete_record - 행을 제거합니다.
• execute_entity - 저장 프로시저 실행
• aggregate_records - 집계 쿼리 수행

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" },
    { "name": "aggregate_records" }
  ]
}

엔티티_설명

현재 역할에 사용할 수 있는 엔터티를 반환합니다. 각 항목에는 필드 이름, 설명 및 허용되는 작업이 포함됩니다. 이 도구는 데이터베이스를 쿼리하지 않습니다. 대신 구성 파일에서 빌드된 메모리 내 구성에서 읽습니다.

매개 변수

예제 요청

{
  "method": "tools/call",
  "params": {
    "name": "describe_entities",
    "arguments": {
      "entities": ["Products"]
    }
  }
}

응답 예제

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing and inventory",
      "fields": [
        {
          "name": "ProductId",
          "description": "Unique product identifier"
        },
        {
          "name": "ProductName",
          "description": "Display name of the product"
        },
        {
          "name": "Price",
          "description": "Retail price in USD"
        }
      ],
      "operations": [
        "read_records",
        "update_record"
      ]
    }
  ]
}

create_record

테이블에 새 행을 만듭니다. 현재 역할에 대한 만들기 권한이 엔터티에 필요합니다. 이 도구는 엔터티 스키마에 대한 입력의 유효성을 검사하고, 필드 수준 권한을 적용하고, 만들기 정책을 적용하고, 생성된 레코드를 생성된 값으로 반환합니다.

매개 변수

레코드 읽기

테이블 또는 뷰를 쿼리합니다. 필터링, 정렬, 페이지 매김 및 필드 선택을 지원합니다. 이 도구는 구조적 매개 변수에서 결정적 SQL을 빌드하고 읽기 권한 및 필드 프로젝션을 적용하며 행 수준 보안 정책을 적용합니다.

매개 변수

페이지 매김 응답

더 많은 결과를 사용할 수 있는 경우 응답에는 커서가 after 포함됩니다. 다음 요청에서 after 이 값을 매개 변수로 전달하여 다음 페이지를 가져옵니다.

{
  "value": [ ... ],
  "after": "W3siRW50aXR5TmFtZ..."
}

필드 after가 있으면 더 많은 페이지가 있음을 나타냅니다. after 없으면 마지막 페이지에 도달했습니다.

JOIN 작업

이 read_records 도구는 단일 테이블 또는 뷰용으로 설계되었습니다. 따라서 JOIN 작업은 이 도구에서 지원되지 않습니다. 이 디자인은 책임을 격리하고, 성능을 향상시키며, 세션의 컨텍스트 창에 미치는 영향을 제한하는 데 도움이 됩니다.

그러나 JOIN 작업은 에지 사례가 아니며 DAB(Data API Builder)는 이미 GraphQL 엔드포인트를 통한 정교한 쿼리를 지원합니다. 더 복잡한 쿼리의 경우 테이블 대신 뷰를 사용하는 것이 좋습니다. 도구를 사용하여 execute_entity 저장 프로시저를 실행하여 매개 변수가 있는 쿼리를 캡슐화할 수도 있습니다.

기록 업데이트

기존 행을 수정합니다. 업데이트하려면 기본 키와 필드가 필요합니다. 이 도구는 기본 키가 존재하는지 확인하고, 업데이트 권한 및 정책을 적용하며, 현재 역할이 수정할 수 있는 업데이트 필드만을 업데이트합니다.

매개 변수

레코드 삭제

기존 행을 제거합니다. 기본 키가 필요합니다. 이 도구는 기본 키가 존재하는지 확인하고, 삭제 권한 및 정책을 적용하고, 트랜잭션 지원을 통해 안전한 삭제를 수행합니다.

매개 변수

실행_엔티티

저장 프로시저를 실행합니다. 입력 매개 변수 및 출력 결과를 지원합니다. 이 도구는 프로시저 서명에 대해 입력 매개 변수의 유효성을 검사하고, 실행 권한을 적용하고, 매개 변수를 안전하게 전달합니다.

매개 변수

aggregate_records

테이블 및 뷰에 대한 집계 쿼리를 수행합니다. 개수, 합계, 평균, 최소 및 최대값과 같은 일반적인 집계 함수를 지원합니다. 이 도구는 구조적 매개 변수에서 결정적 SQL을 빌드하고 읽기 권한 및 필드 프로젝션을 적용하며 행 수준 보안 정책을 적용합니다.

매개 변수

예: groupby 및 having을 사용하여 개수 계산

{
  "method": "tools/call",
  "params": {
    "name": "aggregate_records",
    "arguments": {
      "entity": "Todo",
      "function": "count",
      "field": "*",
      "groupby": ["UserId"],
      "having": { "gt": 2 }
    }
  }
}

이 aggregate-records 도구는 불리언으로 구성하거나 더 많은 설정이 포함된 객체로 구성할 수 있습니다.

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

이 속성은 query-timeout 최대 실행 시간(초)을 지정합니다(범위: 1-600). 이 설정을 사용하면 장기 실행 집계 쿼리가 과도한 리소스를 사용하지 못하도록 방지할 수 있습니다.

런타임 구성

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,
        "aggregate-records": true
      }
    }
  }
}

runtime.mcp.dml-tools 아래의 각 도구 속성은 true 또는 false를 수용합니다. 이 도구는 aggregate-records 다음과 같은 enabledquery-timeout개체 형식도 지원합니다.

{
  "runtime": {
    "mcp": {
      "enabled": true,
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": true,
        "execute-entity": true,
        "aggregate-records": {
          "enabled": true,
          "query-timeout": 30
        }
      }
    }
  }
}

모든 DML 도구를 한 번에 사용하거나 사용하지 않도록 설정하려면 "dml-tools", true, 또는 false를 설정하세요.

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
dab configure --runtime.mcp.dml-tools.aggregate-records.enabled true
dab configure --runtime.mcp.dml-tools.aggregate-records.query-timeout 30

도구 비활성화

런타임 수준에서 도구를 사용하지 않도록 설정하면 엔터티 권한 또는 역할 구성에 관계없이 에이전트에 표시되지 않습니다. 이 설정은 엄격한 운영 경계가 필요한 경우에 유용합니다.

일반적인 시나리오

• 프로덕션 환경에서 데이터 손실을 방지하기 위해 사용하지 않도록 설정 delete-record
• 읽기 전용 보고 엔드포인트에 대해 create-record를 비활성화합니다.
• 저장 프로시저가 사용되지 않는 경우 사용 안 함 execute-entity
• 집계 쿼리가 필요하지 않은 경우 사용 안 함 aggregate-records

도구가 전역적으로 비활성화되면 도구가 list_tools 응답에서 숨겨지고, 호출할 수 없습니다.

엔터티 설정

명시적으로 제한하지 않는 한, 엔터티는 MCP에 자동으로 참여합니다. 엔터티의 mcp 속성은 MCP 참여를 제어합니다. 명시적 컨트롤에 개체 형식을 사용합니다.

개체 형식

{
  "entities": {
    "Products": {
      "mcp": {
        "dml-tools": true
      }
    },
    "SensitiveData": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

엔터티에서 mcp를 지정하지 않으면, MCP가 전역적으로 활성화될 때 DML 도구는 기본적으로 활성화됩니다.

저장 프로시저에 대한 사용자 지정 도구

저장 프로시저 엔터티의 custom-tool 경우 이 속성을 사용하여 프로시저를 명명된 MCP 도구로 등록합니다.

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id"
      },
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

도구별 컨트롤 범위

도구별 토글은 전역 런타임 수준에서만 runtime.mcp.dml-tools로 구성됩니다.

엔터티 수준에서 mcp는 부울 게이트이거나 dml-tools 및 custom-tool 속성을 가진 개체입니다.

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": false
      }
    }
  }
}

{
  "runtime": {
    "mcp": {
      "dml-tools": {
        "describe-entities": true,
        "create-record": true,
        "read-records": true,
        "update-record": true,
        "delete-record": false,
        "execute-entity": true,
        "aggregate-records": true
      }
    }
  }
}

도구는 전역적으로 사용하도록 설정되고 엔터티에서 DML 도구를 허용하는 경우에만 사용할 수 있습니다.

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": [
            {
              "action": "*"
            }
          ]
        }
      ]
    }
  }
}

관련 콘텐츠

• SQL MCP Server 개요
• SQL MCP Server에 의미 체계 설명 추가
• DAB(데이터 API 작성기) 구성 참조
• 엔터티 수준 MCP 구성
• 런타임 MCP 구성
• SQL MCP Server를 Azure Container Apps
• Data API Builder 버전 2.0의 새로운 기능