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

Importante

O SQL Model Context Protocol (MCP) Server está em pré-visualização, e esta documentação e a implementação do motor podem mudar. Embora a versão 1.7 do Data API builder esteja em pré-visualização, deve usar explicitamente a versão pré-lançamento (por exemplo, 1.7.83-rc) porque as funcionalidades MCP ainda não estão incluídas na :latest etiqueta.

O SQL MCP Server expõe seis ferramentas de Linguagem de Manipulação de Dados (DML) a agentes de IA. Estas ferramentas fornecem uma superfície CRUD tipada para operações de base de dados — criando, lendo, atualizando e apagando registos, além de executar procedimentos armazenados. Todas as ferramentas respeitam o controlo de acesso baseado em funções (RBAC), permissões de entidades e políticas definidas na sua configuração.

O que são ferramentas DML?

As ferramentas DML (Data Manipulation Language) tratam de operações de dados: criação, leitura, atualização e eliminação de registos, além de executar procedimentos armazenados. Ao contrário do DDL (Data Definition Language), que modifica o esquema, o DML trabalha exclusivamente no plano de dados em tabelas e vistas existentes.

As seis ferramentas DML são:

• describe_entities - Descobre entidades e operações disponíveis
• create_record - Insere novas linhas
• read_records - Tabelas de consultas e vistas
• update_record - Modifica linhas existentes
• delete_record - Remove linhas
• execute_entity - Executa procedimentos armazenados

Quando as ferramentas DML estão ativadas globalmente e para uma entidade, o SQL MCP Server expõe-as através do protocolo MCP. Os agentes nunca interagem diretamente com o esquema da tua base de dados – funcionam através da camada de abstração do Data API builder.

As ferramentas

list_tools resposta

Quando um agente chama list_tools, SQL MCP Server devolve:

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

describe_entities

Devolve as entidades disponíveis para o papel atual. Cada entrada inclui nomes de campos, tipos de dados, chaves primárias e operações permitidas. Esta ferramenta não consulta a base de dados. Em vez disso, lê a partir da configuração em memória construída a partir do teu ficheiro 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 provêm diretamente de describe_entities. A descrição semântica interna associada a cada ferramenta reforça este fluxo em dois passos.

criar_registo

Cria uma nova linha numa tabela. Requer permissão de criação na entidade para a função atual. A ferramenta valida a entrada contra o esquema da entidade, aplica permissões ao nível do campo, aplica políticas de criação e devolve o registo criado com quaisquer valores gerados.

read_records

Consulta uma tabela ou vista. Suporta filtragem, ordenação, paginação e seleção de campos. A ferramenta constrói SQL determinístico a partir de parâmetros estruturados, aplica permissões de leitura e projeções de campo, e aplica políticas de segurança ao nível das linhas.

Os resultados de read_records são automaticamente armazenados em cache usando o sistema de cache do Data API builder. Pode configurar o tempo de vida em cache (TTL) globalmente ou por entidade para reduzir a carga da base de dados.

atualizar_registro

Modifica uma linha existente. Requer a chave primária e os campos para atualizar. A ferramenta valida a existência da chave primária, aplica permissões e políticas de atualização, e apenas atualiza os campos que o papel atual pode modificar.

apagar_registo

Remove uma fila existente. Requer a chave primária. A ferramenta valida a existência da chave primária, aplica permissões e políticas de eliminação, e realiza eliminações seguras com suporte a transações.

Advertência

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

execute_entity

Executa um procedimento armazenado. Suporta parâmetros de entrada e resultados de saída. A ferramenta valida os parâmetros de entrada em relação à assinatura do procedimento, faz cumprir permissões de execução e passa parâmetros de forma segura.

Configuração em tempo de execução

Configure ferramentas DML globalmente na secção de tempo de execução 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 Data API builder:

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

Desativar ferramentas

Quando desativas uma ferramenta ao nível do tempo de execução, ela nunca é visível para os agentes, independentemente das permissões da entidade ou da configuração da função. Esta configuração é útil quando precisas de limites operacionais rigorosos.

Cenários comuns

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

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

Configurações de entidade

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

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

Se não especificares mcp.dml-tools numa entidade, por defeito assume o valor true quando o MCP está ativado globalmente.

Controlo detalhado

Pode desativar ferramentas específicas para entidades individuais:

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

Esta configuração permite aos agentes criar e ler registos de auditoria, mas impede modificações ou eliminações.

Integração RBAC

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

Se a anonymous função só permite leitura para Products:

• describe_entities Só aparece read_records em operações
• create_record, update_record, e delete_record não estão disponíveis
• Apenas os campos permitidos para anonymous aparecem no esquema

Configurar as funções nos seus 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
• Adição de descrições semânticas ao SQL MCP Server
• Referência de configuração do Data API builder (DAB)
• Deploy SQL MCP Server to Azure Container Apps