[Enh]: Add DML tool: `execute_entity`

[JerryNixon]

What?

execute_entity

A tool to allow an agent to execute a stored procedure or function exposed as a DAB entity.

Behavior

1. Behaves most like the GraphQL flow

2. Entity permissions are enforced

   • Never bypass permissions.
   • On violation, return a standard DAB response payload with an error message (e.g. "You do not have permission to execute this entity").
   • Do not signal errors via HTTP status codes.

3. Parameters

   • Uses the parameter definitions exposed in describe_entities.
   • All Parameters are required.
   • Output Parameters are not supported. (This is DAB standard)
   • Types must match GraphQL data types defined in metadata.
   • If provided values violate constraints, allow the database to fail and return the resulting error in a standard DAB response payload.

4. Returns the execution result

   • The response is a standard DAB payload with the returned dataset (if any).
   • If the procedure returns multiple result sets, return the first one. (This is DAB standard)

5. Key and field handling

   • Keys and fields are not part of this request. Only parameters defined in metadata are valid.

How

• Add execute_entity MCP tool through graphql flow
• Add config property (runtime.mcp.dml-tools.execute-entity.enabled=true)
• Update JSON Schema with runtime.mcp.dml-tools.execute-entity.enabled
• Obey configuration (runtime.mcp.dml-tools.execute-entity.enabled=true)
• Add CLI dab configure --runtime.mcp.dml-tools.execute-entity.enabled true
• Update dab validate (warn when execute-entity.enabled and not mcp.enabled)

Tool method

/// <summary>
/// Executes a stored procedure or function returns the results (if any). 
/// </summary>
Task<DabResponse> ExecuteEntityAsync(
    [Description("The entity name of the procedure or function to execute. "
               + "Must match an entity returned by list_entities with execute=true. Required.")]
    string entity,

    [Description("A dictionary of parameter names and values to pass to the procedure. "
               + "Parameters must match those defined in entity metadata. Optional if no parameters.")]
    IDictionary<string, object?>? parameters = null);

Parameters

• entity (string, required)

  if (string.IsNullOrWhiteSpace(entity))
      throw new ArgumentException("Entity is required", nameof(entity));
  if (!entityMetadata.Execute)
      throw new UnauthorizedAccessException($"Entity {entity} cannot be executed.");

• parameters (IDictionary<string, object?>?, optional)

  if (parameters != null)
  {
      foreach (var param in parameters)
      {
          if (!entityMetadata.Parameters.Contains(param.Key))
              throw new ArgumentException($"Invalid parameter: {param.Key}", nameof(parameters));
      }
  }

Example call

await ExecuteEntityAsync(
    entity: "GetUserByEmail",
    parameters: new Dictionary<string, object?> {
        { "email", "jerry@example.com" }
    });

Output payload

This is a standard Data API builder (DAB) payload which includes errors.

Why?

This allows agents to execute stored procedures or functions configured as entities in DAB.

Configuration

Command line

Add dab --configure runtime.mcp.dml-tools.execute-entity.enabled true