Ferramentas de linguagem de manipulação de dados (DML) no SQL MCP Server

Importante

O SQL MCP Server está em versão prévia e esta documentação e a implementação do mecanismo estão sujeitas a alterações durante esse período de avaliação.

O SQL MCP Server expõe seis ferramentas DML (Linguagem de Manipulação de Dados) para agentes de IA. Essas ferramentas fornecem uma interface CRUD com tipo definido para operações de banco de dados, como criar, ler, atualizar e excluir registros, além de executar procedimentos armazenados. Todas as ferramentas respeitam o RBAC (controle de acesso baseado em função), as permissões de entidade e as políticas definidas em sua configuração.

O que são ferramentas DML?

As ferramentas DML (Linguagem de Manipulação de Dados) lidam com operações de dados: criando, lendo, atualizando e excluindo registros, além de executar procedimentos armazenados. Ao contrário da DDL (Linguagem de Definição de Dados) que modifica o esquema, o DML funciona exclusivamente no plano de dados em tabelas e exibições existentes.

As seis ferramentas DML são:

• describe_entities - Descobre entidades e operações disponíveis
• create_record - Insere novas linhas
• read_records - Consulta tabelas e visões
• update_record – Modifica linhas existentes
• delete_record - Remove linhas
• execute_entity – Executa procedimentos armazenados

Quando as ferramentas DML são habilitadas globalmente e para uma entidade, o SQL MCP Server as expõe por meio do protocolo MCP. Os agentes nunca interagem diretamente com seu esquema de banco de dados – eles funcionam por meio da camada de abstração do construtor de API de Dados.

As ferramentas

resposta list_tools

Quando um agente chama list_tools, o SQL MCP Server retorna:

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

descrever_entidades

Retorna as entidades disponíveis para o papel atual. Cada entrada inclui nomes de campo, tipos de dados, chaves primárias e operações permitidas. Essa ferramenta não consulta o banco de dados. Em vez disso, ele lê a partir da configuração na memória criada a partir do arquivo de configuração.

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

Observação

As opções de entidade usadas por qualquer uma das ferramentas CRUD e DML de execução são provenientes diretamente de describe_entities. A descrição semântica interna anexada a cada ferramenta impõe esse fluxo de duas etapas.

criar_registro

Cria uma nova linha em uma tabela. É necessário ter permissão de criação na entidade para a função atual. A ferramenta valida a entrada no esquema de entidade, impõe permissões de nível de campo, aplica políticas de criação e retorna o registro criado com quaisquer valores gerados.

read_records

Consulta uma tabela ou exibição. Dá suporte à filtragem, classificação, paginação e seleção de campo. A ferramenta cria SQL determinístico com base em parâmetros estruturados, aplica permissões de leitura e projeções de campo e impõe políticas de segurança em nível de linha.

Os resultados de read_records são armazenados em cache automaticamente usando o sistema de cache da API de Dados. Você pode configurar o TTL (tempo de vida útil do cache) globalmente ou por entidade para reduzir a carga do banco de dados.

atualizar_registro

Modifica uma linha existente. Requer que a chave primária e os campos sejam atualizados. A ferramenta valida a chave primária, impõe permissões e políticas de atualização e atualiza apenas os campos que a função atual pode modificar.

excluir_registro

Remove uma linha existente. Requer a chave primária. A ferramenta valida a chave primária, impõe permissões e políticas de exclusão e executa a exclusão segura com suporte à transação.

Aviso

Alguns cenários de produção desabilitarão essa ferramenta globalmente para restringir amplamente os modelos.

executar_entidade

Executa um procedimento armazenado. Dá suporte a parâmetros de entrada e resultados de saída. A ferramenta valida parâmetros de entrada na assinatura do procedimento, impõe permissões de execução e passa parâmetros com segurança.

Configuração de runtime

Configure as ferramentas DML globalmente na seção de runtime do seu 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
      }
    }
  }
}

Usando a CLI

Defina propriedades individualmente usando a CLI do construtor de API de Dados:

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

Desabilitando ferramentas

Quando você desabilitar uma ferramenta no nível de runtime, ela nunca será exibida aos agentes, independentemente das permissões de entidade ou da configuração de função. Essa configuração é útil quando você precisa de limites operacionais rígidos.

Cenários comuns

• Desabilitar delete-record para evitar perda de dados na produção
• Desativar create-record para endpoints de relatórios somente leitura
• Desabilitar execute-entity quando os procedimentos armazenados não são usados

Quando uma ferramenta é desabilitada globalmente, a ferramenta fica oculta da list_tools resposta e não pode ser invocada.

Configurações de entidade

As entidades participam do MCP automaticamente, a menos que você as restrinja explicitamente. A dml-tools propriedade existe para que você possa excluir uma entidade do MCP ou restringir seus recursos, mas você não precisa definir nada para uso normal.

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

Se você não especificar mcp.dml-tools em uma entidade, ela usará como padrão true quando o MCP estiver habilitado globalmente.

Controle detalhado

Você pode desabilitar ferramentas específicas para entidades individuais:

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

Essa configuração permite que os agentes criem e leiam logs de auditoria, mas impede a modificação ou exclusão.

Integração do RBAC

Cada operação de ferramenta DML aplica as suas regras de controle de acesso baseadas em função. A função de um agente determina quais entidades são visíveis, quais operações são permitidas, quais campos são incluídos e se as políticas de nível de linha se aplicam.

Se a anonymous função permitir apenas permissão de leitura em Products:

• describe_entities mostra read_records apenas em operações
• create_record, update_recorde delete_record não estão disponíveis
• Somente campos permitidos para anonymous aparecem no esquema

Configure funções em seu dab-config.json:

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

Conteúdo relacionado

• Visão geral do SQL MCP Server
• Adicionando descrições semânticas ao SQL MCP Server
• Referência de configuração do DAB (Construtor de API de Dados)
• Implantar o SQL MCP Server nos Aplicativos de Contêiner do Azure