Configuración de herramientas de MCP personalizadas para procedimientos almacenados

Importante

Sql Model Context Protocol (MCP) Server está disponible en Data API Builder versión 1.7 y posteriores.

Nota:

La funcionalidad de SQL MCP Server 2.0 descrita en esta sección se encuentra actualmente en versión preliminar y podría cambiar antes de la disponibilidad general. Para obtener más información, consulte Novedades de la versión 2.0.

SQL MCP Server expone tablas y vistas a través de herramientas genéricas del lenguaje de manipulación de datos (DML). En el caso de los procedimientos almacenados, puede ir más allá: establecer custom-tool: true en la entidad para que el procedimiento aparezca en la lista de herramientas de MCP como una herramienta con nombre y creada específicamente. Los agentes de inteligencia artificial lo detectan por nombre, ven su descripción y lo llaman directamente, sin SQL necesario.

Importante

Los nombres de herramientas personalizados se derivan del nombre de entidad, pero se convierten en snake_case. Por ejemplo, una entidad denominada GetProductById se convierte get_product_by_id en la lista de herramientas de MCP. Use el nombre del snake_case al llamar a la herramienta. El nombre de la entidad PascalCase no se acepta como un nombre de herramienta.

El resto de este artículo muestra cómo agregar, configurar y probar una herramienta de MCP personalizada respaldada por un procedimiento almacenado.

Prerrequisitos

  • Data API Builder versión 2.0 o posterior
  • Base de datos de SQL Server con al menos un procedimiento almacenado
  • Un existente dab-config.json con MCP habilitado
  • CLI de DAB instalada

Habilitación de MCP en la configuración

Si aún no lo ha hecho, habilite MCP en la sección runtime.

dab configure --runtime.mcp.enabled true

Esto agrega lo siguiente a dab-config.json:

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

Añadir el procedimiento almacenado como una herramienta personalizada

Utiliza dab add con --source.type stored-procedure y --mcp.custom-tool true.

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

Esto genera la siguiente entidad en 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 propiedad solo es válida en entidades de procedimiento almacenado. Si se establece en una tabla o una vista, se produce un error de configuración durante el inicio.

Añade una descripción para mejorar la precisión del agente

Sin una descripción, los agentes solo ven el nombre GetProductByIdtécnico . Con una descripción, comprenden lo que hace y cuándo 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
      }
    }
  }
}

Comprobación de que la herramienta aparece en la lista de herramientas

Inicie DAB y llame al tools/list punto de conexión de MCP para confirmar que la herramienta está registrada.

Cuando un cliente MCP llama a tools/list, la respuesta incluye la herramienta personalizada junto con las herramientas 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": {}
      }
    }
  ]
}

Nota:

La denominación de la herramienta utiliza snake_case (por ejemplo, get_product_by_id para la entidad GetProductById). inputSchema actualmente devuelve un objeto vacío properties. Los agentes se basan en la descripción de la herramienta y describe_entities para determinar los parámetros correctos.

Configuración de varias herramientas personalizadas

Puede registrar varios procedimientos almacenados como herramientas personalizadas en la misma configuración.

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 qué roles pueden llamar a la herramienta

Las herramientas personalizadas respetan el mismo control de acceso basado en rol (RBAC) que todas las demás entidades DAB. Establezca permissions en la entidad para restringir qué roles pueden ejecutar el procedimiento.

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

Cuando un agente llama con el rol de anonymous, get_order_summary no aparece en tools/list y cualquier tools/call directo devuelve un error de permiso.

Deshabilitar una herramienta personalizada sin quitarla

Establezca custom-tool a false para ocultar la herramienta a los agentes sin eliminar la entidad.

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

La entidad permanece en la configuración y puede volver a habilitarla más adelante estableciendo --mcp.custom-tool true.

Contenido relacionado

  • Last updated on