Compartilhar via

Configurar ferramentas personalizadas do MCP para procedimentos armazenados

Importante

O SERVIDOR MCP (Protocolo de Contexto do Modelo SQL) está disponível no Construtor de API de Dados versão 1.7 e posterior.

Observação

A funcionalidade do SQL MCP Server 2.0 descrita nesta seção está atualmente em versão prévia e pode ser alterada antes da disponibilidade geral. Para obter mais informações, consulte o que há de novo na versão 2.0.

O SQL MCP Server expõe tabelas e exibições por meio de ferramentas de DML (linguagem de manipulação de dados) genéricas. Para procedimentos armazenados, você pode ir mais longe: definir custom-tool: true na entidade para que o procedimento apareça na lista de ferramentas do MCP como uma ferramenta nomeada e criada com finalidade. Os agentes de IA a descobrem pelo nome, veem sua descrição e a chamam diretamente , sem necessidade de SQL.

Importante

Os nomes de ferramentas personalizadas são derivados do nome da entidade, mas convertidos em snake_case. Por exemplo, uma entidade nomeada GetProductById se torna na lista de ferramentas get_product_by_id do MCP. Use o nome snake_case ao chamar a ferramenta. O nome da entidade PascalCase não é aceito como um nome de ferramenta.

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

Pré-requisitos

  • Construtor de API de Dados versão 2.0 ou posterior
  • Banco de dados do SQL Server com pelo menos um procedimento armazenado
  • Um dab-config.json existente com MCP habilitado
  • CLI do DAB instalada

Habilitar o MCP em sua configuração

Caso ainda não tenha feito isso, habilite o MCP na seção de runtime.

dab configure --runtime.mcp.enabled true

Isso adiciona 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

Isso 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 em uma tabela ou exibir entidade resulta em um erro de configuração na inicialização.

Adicionar 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 entendem o que ele faz e quando 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
      }
    }
  }
}

Verificar se a ferramenta aparece na lista de ferramentas

Inicie o DAB e chame o tools/list endpoint MCP para confirmar se a ferramenta está registrada.

dab start

Quando um cliente MCP chama tools/list, a resposta inclui sua ferramenta personalizada junto 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 entidade GetProductById). O inputSchema atualmente retorna vazio properties. Os agentes dependem da descrição da ferramenta e describe_entities para determinar os parâmetros corretos.

Configurar várias ferramentas personalizadas

Você pode registrar vários 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 funções podem chamar a ferramenta

As ferramentas personalizadas respeitam o mesmo controle de acesso baseado em função (RBAC) que todas as outras entidades do DAB. Defina o permissions na entidade para restringir quais funções 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 chama com a função anonymous, get_order_summary não aparece em tools/list e qualquer tentativa direta de tools/call retorna um erro de permissão.

Desabilitar uma ferramenta personalizada sem removê-la

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

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

A entidade permanece na configuração e você pode habilitá-la novamente mais tarde definindo --mcp.custom-tool true.

Conteúdo relacionado

  • Last updated on