NOTE: Before you start, lets discuss calling this tool create_record.

What?

create_entity

A tool to allow an agent to create a single record.

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 create this entity").
   • Do not signal errors via HTTP status codes.

3. Supports partial field lists

   • Requests may specify only a subset of fields.
   • Whether a field is required is not determined by metadata. A request may omit required fields in error.
   • If required fields are missing, allow the database to fail and return the resulting error in a standard DAB response payload.

4. Returns the created entity

   • The response includes only the combination of keys and fields supplied in the request.
   • If an autogen key was not supplied, include it in the response.
   • Example: a table with 100 columns, request with 10 fields → response contains those 10 fields (plus autogen keys, if any).

5. Key handling

   • Keys use the entity’s mapped aliases.
   • Non-autogen keys are required in the request.
   • Autogen keys are optional in the request.
   • Autogen keys can be included in the request as null.

6. Field handling

   • Fields use the entity’s mapped aliases.

How

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

Tool method

/// <summary>
/// Creates a new record in the specified entity. 
/// Returns only the requested keys and fields (plus any autogen keys, if applicable).
/// </summary>
Task<DabResponse> CreateEntityAsync(
    [Description("The entity name of the record to create. Must match an entity returned from list_entities with create=true. Required.")]
    string entity,

    [Description("A dictionary of key/value pairs identifying the record’s keys. Keys must match those defined in entity metadata. Optional for autogen keys.")]
    IDictionary<string, object?>? keys,

    [Description("A dictionary of field/value pairs to insert. Fields must match those defined in entity metadata. At least one field is required.")]
    IDictionary<string, object?> fields);

Parameters

• entity (string, required)

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

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

if (keys == null)
    keys = new Dictionary<string, object?>();

foreach (var key in keys.Keys)
{
    if (!entityMetadata.Keys.Contains(key))
        throw new ArgumentException($"Invalid key: {key}", nameof(keys));
}

• fields (IDictionary<string, object?>, required)

if (fields == null || fields.Count == 0)
    throw new ArgumentException("At least one field is required", nameof(fields));

foreach (var field in fields.Keys)
{
    if (!entityMetadata.Fields.Contains(field))
        throw new ArgumentException($"Invalid field: {field}", nameof(fields));
}

Example call

await CreateEntityAsync(
    entity: "User",
    keys: new Dictionary<string, object?> { { "Id", null } },
    fields: new Dictionary<string, object?> {
        { "email", null },
        { "name", "Jerry Nixon" }
    });

Output payload

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

Why?

This allows agents to create new records.

Configuration

Command line

Add dab --configure mcp.dml-tools.create-entity.enabled true