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

Sql Model Context Protocol (MCP) Server expone siete herramientas de lenguaje de manipulación de datos (DML) a agentes de IA. Estas herramientas proporcionan una interfaz tipada para operaciones CRUD en bases de datos: creación, lectura, actualización y eliminación de registros, agregación de datos, además de la ejecución de 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, agregar datos, 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 siete 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
• aggregate_records - Realiza consultas de agregación

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

describe_entities

Devuelve las entidades disponibles para el rol actual. Cada entrada incluye nombres de campo, descripciones 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.

Parámetros

Solicitud de ejemplo

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

Respuesta de ejemplo

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

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.

Parámetros

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.

Parámetros

Respuesta de paginación

Cuando haya más resultados disponibles, la respuesta incluye un after cursor. Pase este valor como parámetro after en la siguiente solicitud para capturar la página siguiente.

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

La presencia del after campo indica que existen más páginas. Cuando after está ausente, ha llegado a la última página.

Operaciones JOIN

La read_records herramienta está diseñada para una sola tabla o vista. Como resultado, las operaciones JOIN no se admiten en esta herramienta. Este diseño ayuda a aislar la responsabilidad, mejorar el rendimiento y limitar el impacto en la ventana de contexto de la sesión.

Sin embargo, las operaciones JOIN no son un caso atípico, y Data API Builder (DAB) ya admite consultas sofisticadas a través del punto de conexión GraphQL. Para consultas más complejas, se recomienda usar una vista en lugar de una tabla. También puede usar la execute_entity herramienta para ejecutar procedimientos almacenados para encapsular consultas con parámetros.

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.

Parámetros

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.

Parámetros

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.

Parámetros

agregar_registros

Realiza consultas de agregación en tablas y vistas. Admite funciones de agregado comunes, como count, sum, average, minimum y maximum. 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.

Parámetros

Ejemplo: recuento con groupby y tener

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

La aggregate-records herramienta se puede configurar como un valor booleano o como un objeto con más opciones:

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

La query-timeout propiedad especifica el tiempo máximo de ejecución en segundos (intervalo: 1–600). Esta configuración ayuda a evitar que las consultas de agregación de ejecución prolongada consuman recursos excesivos.

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

Cada parámetro de la herramienta en runtime.mcp.dml-tools acepta true o false. La aggregate-records herramienta también admite un formato de objeto con enabled y query-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
        }
      }
    }
  }
}

Para habilitar o deshabilitar todas las herramientas DML a la vez, establezca el valor de "dml-tools" en true o false.

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

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
• Deshabilitar aggregate-records cuando no se necesitan consultas de agregación

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 mcp propiedad de una entidad controla su participación en MCP. Use el formato de objeto para el control explícito.

Formato de objeto

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

Si no especifica mcp en una entidad, las herramientas DML se habilitan de forma predeterminada cuando MCP está habilitado globalmente.

Herramientas personalizadas para procedimientos almacenados

Para las entidades de procedimiento almacenado, use la custom-tool propiedad para registrar el procedimiento como una herramienta MCP con nombre:

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

Ámbito del control por herramienta

Los interruptores por herramienta solo se configuran en el nivel global de tiempo de ejecución en runtime.mcp.dml-tools.

En el nivel de entidad, mcp es una puerta booleana o un objeto con dml-tools propiedades y 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
      }
    }
  }
}

Una herramienta solo está disponible si está habilitada globalmente y la entidad permite herramientas DML.

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

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)
• Configuración de MCP de nivel de entidad
• Configuración de MCP en tiempo de ejecución
• Desplegar SQL MCP Server en Azure Container Apps
• Novedades de Data API Builder, versión 2.0