Configurar ferramentas MCP personalizadas para procedimentos armazenados

Importante

O SQL Model Context Protocol (MCP) Server está disponível no Data API builder versão 1.7 e posteriores.

Observação

A funcionalidade SQL MCP Server 2.0 descrita nesta secção está atualmente em pré-visualização e pode mudar antes da disponibilidade geral. Para mais informações, consulte O que há de novo na versão 2.0.

O SQL MCP Server expõe tabelas e vistas através de ferramentas genéricas de linguagem de manipulação de dados (DML). Para procedimentos armazenados, pode ir mais longe: definir custom-tool: true na entidade para que o procedimento apareça na lista de ferramentas MCP como uma ferramenta nomeada e construída para um propósito. Os agentes de IA descobrem-no pelo nome, veem a descrição e chamam-no diretamente — sem necessidade de SQL.

Importante

Os nomes de ferramentas personalizadas derivam do nome da entidade, mas são convertidos para snake_case. Por exemplo, uma entidade nomeada GetProductById passa a get_product_by_id fazer parte da lista de ferramentas MCP. Use o nome snake_case ao chamar a ferramenta. O nome da entidade PascalCase não é aceite como nome de ferramenta.

O resto deste artigo mostra como adicionar, configurar e testar uma ferramenta MCP personalizada apoiada por um procedimento armazenado.

Pré-requisitos

  • Data API builder versão 2.0 ou posterior
  • Base de dados SQL Server com pelo menos um procedimento armazenado
  • Um existente dab-config.json com MCP ativado
  • DAB CLI instalado

Ative o MCP na sua configuração

Se ainda não o fizeste, ativa o MCP na secção de tempo de execução.

dab configure --runtime.mcp.enabled true

Isto acrescenta o seguinte ao seu dab-config.json:

{
  "runtime": {
    "mcp": {
      "enabled": true
    }
  }
}

Adicionar o procedimento armazenado como uma ferramenta personalizada

Use dab add com --source.type stored-procedure e --mcp.custom-tool true.

dab add GetProductById \
  --source dbo.get_product_by_id \
  --source.type "stored-procedure" \
  --permissions "anonymous:execute" \
  --mcp.custom-tool true

Isto produz a seguinte entidade em dab-config.json:

{
  "entities": {
    "GetProductById": {
      "source": {
        "object": "dbo.get_product_by_id",
        "type": "stored-procedure"
      },
      "graphql": {
        "enabled": true,
        "operation": "mutation",
        "type": {
          "singular": "GetProductById",
          "plural": "GetProductByIds"
        }
      },
      "rest": {
        "enabled": true,
        "methods": [
          "post"
        ]
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ],
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

Importante

A custom-tool propriedade só é válida em entidades de procedimento armazenado. Defini-lo numa tabela ou entidade de visualização resulta num erro de configuração no arranque.

Adicione uma descrição para melhorar a precisão do agente

Sem uma descrição, os agentes veem apenas o nome GetProductByIdtécnico . Com uma descrição, eles percebem o que faz e quando devem usá-lo.

dab update GetProductById \
  --description "Returns full product details including pricing and inventory for a given product ID"

{
  "entities": {
    "GetProductById": {
      "description": "Returns full product details including pricing and inventory for a given product ID",
      "source": {
        "object": "dbo.get_product_by_id",
        "type": "stored-procedure"
      },
      "fields": [],
      "graphql": {
        "enabled": true,
        "operation": "mutation",
        "type": {
          "singular": "GetProductById",
          "plural": "GetProductByIds"
        }
      },
      "rest": {
        "enabled": true,
        "methods": [
          "post"
        ]
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ],
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

Verifique se a ferramenta aparece na lista de ferramentas

Inicia o DAB e liga para o tools/list endpoint MCP para confirmar que a ferramenta está registada.

dab start

Quando um cliente MCP chama tools/list, a resposta inclui a sua ferramenta personalizada juntamente com as ferramentas DML:

{
  "tools": [
    {
      "name": "get_product_by_id",
      "description": "Returns full product details including pricing and inventory for a given product ID",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

Observação

O nome da ferramenta usa snake_case (por exemplo, get_product_by_id para a GetProductById entidade). O inputSchema atualmente retorna um properties vazio. Os agentes baseiam-se na descrição da ferramenta e describe_entities na determinação dos parâmetros corretos.

Configurar múltiplas ferramentas personalizadas

Pode registar múltiplos procedimentos armazenados como ferramentas personalizadas na mesma configuração.

dab add SearchProducts \
  --source dbo.search_products \
  --source.type "stored-procedure" \
  --permissions "anonymous:execute" \
  --mcp.custom-tool true \
  --description "Full-text search across product names and descriptions"

dab add GetOrderSummary \
  --source dbo.get_order_summary \
  --source.type "stored-procedure" \
  --permissions "authenticated:execute" \
  --mcp.custom-tool true \
  --description "Returns order totals and line item counts for a given customer"

Controlar quais as funções que podem chamar a ferramenta

As ferramentas personalizadas respeitam o mesmo controlo de acesso baseado em funções (RBAC) que todas as outras entidades DAB. Defina o permissions na entidade para restringir quais os papéis que podem executar o procedimento.

{
  "entities": {
    "GetOrderSummary": {
      "source": {
        "object": "dbo.get_order_summary",
        "type": "stored-procedure"
      },
      "graphql": {
        "enabled": true,
        "operation": "mutation",
        "type": {
          "singular": "GetOrderSummary",
          "plural": "GetOrderSummarys"
        }
      },
      "rest": {
        "enabled": true,
        "methods": [
          "post"
        ]
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "execute"
            }
          ]
        }
      ],
      "mcp": {
        "custom-tool": true
      }
    }
  }
}

Quando um agente faz uma chamada com a função anonymous, get_order_summary não aparece em tools/list e qualquer acesso direto tools/call resulta num erro de permissão.

Desative uma ferramenta personalizada sem a remover

Defina custom-tool para false ocultar a ferramenta dos agentes sem apagar a entidade.

dab update GetProductById \
  --mcp.custom-tool false

A entidade mantém-se na configuração e pode ser reativada mais tarde definindo --mcp.custom-tool true.

Conteúdo relacionado

  • Last updated on