Herramientas del lenguaje de manipulación de datos (DML) en SQL MCP Server

Importante

SQL MCP Server está en versión preliminar y esta documentación y la implementación del motor está sujeta a cambios durante este período de evaluación.

SQL MCP Server expone seis herramientas de lenguaje de manipulación de datos (DML) a agentes de IA. Estas herramientas proporcionan una interfaz CRUD tipada para las operaciones de base de datos: crear, leer, actualizar y eliminar registros, además de ejecutar procedimientos almacenados. Todas las herramientas respetan el control de acceso basado en rol (RBAC), los permisos de entidad y las directivas definidas en la configuración.

¿Qué son las herramientas DML?

Las herramientas DML (lenguaje de manipulación de datos) controlan las operaciones de datos: crear, leer, actualizar y eliminar registros, además de ejecutar procedimientos almacenados. A diferencia de DDL (lenguaje de definición de datos) que modifica el esquema, DML funciona exclusivamente en el plano de datos de las tablas y vistas existentes.

Las seis herramientas DML son:

• describe_entities - Detecta entidades y operaciones disponibles.
• create_record - Inserta nuevas filas.
• read_records - Consultas de tablas y vistas
• update_record - Modifica las filas existentes.
• delete_record - Elimina las filas.
• execute_entity - Ejecuta procedimientos almacenados

Cuando las herramientas DML están habilitadas globalmente y para una entidad, SQL MCP Server las expone a través del protocolo MCP. Los agentes nunca interactúan directamente con el esquema de la base de datos: funcionan a través de la capa de abstracción del generador de data API.

Herramientas

list_tools respuesta

Cuando un agente llama a list_tools, SQL MCP Server devuelve:

{
  "tools": [
    { "name": "describe_entities" },
    { "name": "create_record" },
    { "name": "read_records" },
    { "name": "update_record" },
    { "name": "delete_record" },
    { "name": "execute_entity" }
  ]
}

describe_entities

Devuelve las entidades disponibles para el rol actual. Cada entrada incluye nombres de campo, tipos de datos, claves principales y operaciones permitidas. Esta herramienta no consulta la base de datos. En su lugar, lee de la configuración en memoria creada a partir del archivo de configuración.

{
  "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"
      ]
    }
  ]
}

Nota:

Las opciones de entidad usadas por cualquier herramienta CRUD y ejecutante de DML proceden directamente de describe_entities. La descripción semántica interna adjunta a cada herramienta aplica este flujo de dos pasos.

crear_registro

Crea una nueva fila en una tabla. Requiere permiso de creación en la entidad para el rol actual. La herramienta valida la entrada en el esquema de entidad, aplica permisos de nivel de campo, aplica directivas de creación y devuelve el registro creado con los valores generados.

read_records

Consulta una tabla o vista. Admite el filtrado, la ordenación, la paginación y la selección de campos. La herramienta compila SQL determinista a partir de parámetros estructurados, aplica permisos de lectura y proyecciones de campo y aplica directivas de seguridad de nivel de fila.

Los resultados de read_records se almacenan automáticamente en caché mediante el sistema de almacenamiento en caché de Data API Builder. Puede configurar el período de vida (TTL) de caché global o por entidad para reducir la carga de la base de datos.

actualizar_registro

Modifica una fila existente. Requiere que se actualicen los campos y la clave principal. La herramienta valida que la clave principal existe, aplica los permisos y directivas de actualización, y solo actualiza los campos que el rol actual puede modificar.

eliminar_registro

Quita una fila existente. Requiere la clave principal. La herramienta valida que la clave principal existe, aplica permisos y directivas de eliminación y realiza una eliminación segura con compatibilidad con transacciones.

Advertencia

Algunos escenarios de producción deshabilitarán esta herramienta globalmente para restringir ampliamente los modelos.

execute_entity

Ejecuta un procedimiento almacenado. Admite parámetros de entrada y resultados de salida. La herramienta valida los parámetros de entrada en la firma del procedimiento, aplica permisos de ejecución y pasa parámetros de forma segura.

Configuración en tiempo de ejecución

Configure las herramientas de DML globalmente en la sección en tiempo de ejecución de dab-config.json:

{
  "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
      }
    }
  }
}

Uso de la CLI

Establezca las propiedades individualmente mediante la CLI del Generador de API de datos:

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

Deshabilitación de herramientas

Al deshabilitar una herramienta a nivel de ejecución, nunca aparece a los agentes, independientemente de los permisos de entidad o la configuración de roles. Esta configuración es útil cuando se necesitan límites operativos estrictos.

Escenarios frecuentes

• Deshabilitar delete-record para evitar la pérdida de datos en producción
• Deshabilitar create-record para puntos de conexión de generación de informes de solo lectura
• Deshabilitar execute-entity cuando no se usan procedimientos almacenados

Cuando una herramienta está deshabilitada globalmente, la herramienta está oculta de la list_tools respuesta y no se puede invocar.

Configuración de entidad

Las entidades participan automáticamente en MCP a menos que las restrinja explícitamente. La dml-tools propiedad existe para que pueda excluir una entidad de MCP o restringir sus funcionalidades, pero no es necesario establecer nada para su uso normal.

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

Si no especifica mcp.dml-tools en una entidad, el valor predeterminado es true cuando MCP está habilitado globalmente.

Control detallado

Puede deshabilitar herramientas específicas para entidades individuales:

{
  "entities": {
    "AuditLogs": {
      "mcp": {
        "dml-tools": {
          "create-record": true,
          "read-records": true,
          "update-record": false,
          "delete-record": false
        }
      }
    }
  }
}

Esta configuración permite a los agentes crear y leer registros de auditoría, pero evita la modificación o eliminación.

Integración de RBAC

Cada operación de herramienta de DML aplica las reglas de control de acceso basadas en roles. El rol de un agente determina qué entidades están visibles, qué operaciones se permiten, qué campos se incluyen y si se aplican directivas de nivel de fila.

Si el rol solo permite el anonymous permiso de lectura en Products:

• describe_entities solo se muestra read_records en las operaciones
• create_record, update_recordy delete_record no están disponibles
• Solo los campos permitidos para anonymous aparecen en el esquema

Configura roles en dab-config.json:

{
  "entities": {
    "Products": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "include": ["ProductId", "ProductName", "Price"],
                "exclude": ["Cost"]
              }
            }
          ]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Contenido relacionado

• Información general sobre SQL MCP Server
• Adición de descripciones semánticas a SQL MCP Server
• Referencia de configuración de Data API Builder (DAB)
• Implementación de SQL MCP Server en Azure Container Apps