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

O SERVIDOR MCP (Protocolo de Contexto de Modelo SQL) expõe sete ferramentas DML (Linguagem de Manipulação de Dados) para agentes de IA. Essas ferramentas fornecem uma interface CRUD tipada para operações de banco de dados — como criar, ler, atualizar e excluir registros, agregar dados, 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: criação, leitura, atualização e exclusão de registros, agregação de dados e execução de 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 sete 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
• aggregate_records – Executa consultas de agregação

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

descrever_entidades

Retorna as entidades disponíveis para o papel atual. Cada entrada inclui nomes de campo, descrições 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.

Parâmetros

Solicitação de exemplo

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

Resposta de exemplo

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

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.

Parâmetros

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.

Parâmetros

Resposta de paginação

Quando mais resultados estão disponíveis, a resposta inclui um after cursor. Passe esse valor como parâmetro after na próxima solicitação para buscar a próxima página.

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

A presença do after campo indica que existem mais páginas. Quando after estiver ausente, você chegou à última página.

Operações JOIN

A read_records ferramenta foi projetada para uma única tabela ou exibição. Como resultado, as operações JOIN não têm suporte nesta ferramenta. Esse design ajuda a isolar a responsabilidade, melhorar o desempenho e limitar o impacto na janela de contexto da sessão.

No entanto, as operações JOIN não são um caso atípico, e o Construtor de API de Dados (DAB) já oferece suporte a consultas sofisticadas por meio do endpoint GraphQL. Para consultas mais complexas, recomendamos usar uma exibição em vez de uma tabela. Você também pode usar a execute_entity ferramenta para executar procedimentos armazenados para encapsular consultas parametrizadas.

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.

Parâmetros

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.

Parâmetros

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.

Parâmetros

agregar_registros

Executa consultas de agregação em tabelas e exibições. Dá suporte a funções de agregação comuns, como contagem, soma, média, mínimo e máximo. 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.

Parâmetros

Exemplo: contar com groupby e ter

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

A aggregate-records ferramenta pode ser configurada como um booliano ou como um objeto com mais configurações:

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

A query-timeout propriedade especifica o tempo máximo de execução em segundos (intervalo: 1 a 600). Essa configuração ajuda a impedir que consultas de agregação de execução prolongada consumam recursos excessivos.

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

Cada propriedade de ferramenta em runtime.mcp.dml-tools aceita true ou false. A aggregate-records ferramenta também dá suporte a um formato de objeto com enabled e 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 ou desabilitar todas as ferramentas DML de uma só vez, defina "dml-tools" como true ou false.

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

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
• Desabilitar aggregate-records quando as consultas de agregação não forem necessárias

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 propriedade mcp de uma entidade controla sua participação no MCP. Use o formato de objeto para controle explícito.

Formato do objeto

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

Se você não especificar mcp em uma entidade, as ferramentas DML serão habilitadas por padrão quando o MCP estiver habilitado globalmente.

Ferramentas personalizadas para procedimentos armazenados

Para entidades de procedimento armazenado, utilize a propriedade custom-tool para registrar o procedimento como uma ferramenta MCP identificada:

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

Escopo do controle individual por ferramenta

Os alternadores por ferramenta são configurados apenas no nível global de tempo de execução em runtime.mcp.dml-tools.

No nível da entidade, mcp é uma porta lógica ou um objeto com propriedades dml-tools e 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
      }
    }
  }
}

Uma ferramenta só estará disponível se estiver habilitada globalmente e a entidade permitir ferramentas DML.

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

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)
• Configuração do MCP no nível da entidade
• Configuração do MCP de runtime
• Deploy SQL MCP Server para Azure Container Apps
• Novidades no Construtor de API de Dados versão 2.0