Configurare strumenti personalizzati MCP per procedure memorizzate

Importante

Il server MCP (SQL Model Context Protocol) è disponibile in Generatore API dati versione 1.7 e successive.

Annotazioni

La funzionalità SQL MCP Server 2.0 descritta in questa sezione è attualmente in anteprima e potrebbe cambiare prima della disponibilità generale. Per altre informazioni, vedere Novità della versione 2.0.

SQL MCP Server espone tabelle e viste tramite strumenti DML (Data Manipulation Language) generici. Per le stored procedure, è possibile procedere ulteriormente: impostare custom-tool: true sull'entità in modo che la procedura venga visualizzata nell'elenco degli strumenti MCP come strumento denominato appositamente creato. Gli agenti di intelligenza artificiale lo individuano in base al nome, visualizzano la descrizione e lo chiamano direttamente, senza richiedere SQL.

Importante

I nomi degli strumenti personalizzati sono derivati dal nome dell'entità, ma convertiti in snake_case. Ad esempio, un'entità denominata GetProductById diventa get_product_by_id nell'elenco degli strumenti MCP. Usare il nome snake_case quando si chiama lo strumento. Il nome dell'entità PascalCase non viene accettato come nome dello strumento.

Nella parte restante di questo articolo viene illustrato come aggiungere, configurare e testare uno strumento MCP personalizzato supportato da una stored procedure.

Prerequisiti

  • Generatore API dati versione 2.0 o successiva
  • Database di SQL Server con almeno una stored procedure
  • dab-config.json esistente con MCP abilitato
  • DAB CLI installato

Abilitare MCP nella configurazione

Se non è già stato fatto, abilitare MCP nella sezione runtime.

dab configure --runtime.mcp.enabled true

Questo aggiunge quanto segue a dab-config.json:

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

Aggiungere la procedura memorizzata come strumento personalizzato

Usare dab add con --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

In questo modo viene prodotta la seguente entità in 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

La custom-tool proprietà è valida solo nelle entità stored procedure. Impostarlo su una tabella o un'entità di visualizzazione genera un errore di configurazione all'avvio.

Aggiungere una descrizione per migliorare l'accuratezza dell'agente

Senza una descrizione, gli agenti visualizzano solo il nome GetProductByIdtecnico . Con una descrizione, capiscono cosa fa e quando usarlo.

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
      }
    }
  }
}

Verificare che lo strumento venga visualizzato nell'elenco degli strumenti

Avviare DAB e chiamare l'endpoint tools/list MCP per verificare che lo strumento sia registrato.

dab start

Quando un client MCP chiama tools/list, la risposta include lo strumento personalizzato insieme agli strumenti 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": {}
      }
    }
  ]
}

Annotazioni

Il nome dello strumento usa il formato snake_case (ad esempio, get_product_by_id per l'entità GetProductById). L'oggetto inputSchema restituisce attualmente un valore vuoto properties. Gli agenti si basano sulla descrizione dello strumento e describe_entities per determinare i parametri corretti.

Configurare più strumenti personalizzati

È possibile registrare più stored procedure come strumenti personalizzati nella stessa configurazione.

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"

Controllare quali ruoli possono chiamare lo strumento

Gli strumenti personalizzati rispettano lo stesso controllo degli accessi in base al ruolo (RBAC) di tutte le altre entità DAB. Configurare l'attributo permissions sull'entità per vincolare i ruoli che possono eseguire la procedura.

{
  "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 un agente chiama con il anonymous ruolo, get_order_summary non viene visualizzato in tools/list e qualsiasi accesso diretto a tools/call restituisce un errore di autorizzazione.

Disabilitare uno strumento personalizzato senza rimuoverlo

Impostare custom-tool su false per nascondere lo strumento dagli agenti senza eliminare l'entità.

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

L'entità rimane nella configurazione ed è possibile riabilitarla in un secondo momento impostando --mcp.custom-tool true.

Contenuti correlati

  • Last updated on