Skip to content

mcp_upsert_column

Jump to bottom
PhuocLe edited this page Jun 20, 2026 · 3 revisions

Summary

Field Value
Tool name upsert_column
MCP title Create or update a table column
Category advanced
Implementation DynamicsCrm.DevKit.Cli/Mcp/Tools/UpsertColumnTool.cs
Estimated token count ~1141 tokens (tools/list tool JSON, o200k_base, measured 2026-06-18)
Last verified 2026-06-18

MCP Tool Description (Exact)

Dataverse column (attribute) — auto-detect create vs update. Types: string, memo, integer, bigint, decimal, money, float, boolean, datetime, lookup, customer, picklist, multipicklist, image, file.

CREATE (no attribute): need attribute_type + display_name.
- schema_name: if provided, used as-is as SchemaName (skip auto-derive from display_name)
- lookup: needs lookup_target (auto-creates 1:N)
- customer: polymorphic (account+contact), no lookup_target
- picklist/multipicklist: options JSON or global_optionset_name

UPDATE (exists): attribute_type ignored (immutable). picklist: use add/update/delete_options. Omit params to keep current.

attribute_name needs publisher prefix or solution_name to auto-resolve.

WHEN TO USE:
- Create new attribute on an existing table (need attribute_type + display_name)
- Update mutable metadata, format, required_level, picklist options
- Add/rename/remove options on an existing picklist via add_options/update_options/delete_options

FUZZY/AMBIGUITY:
- entity_name resolves Display Name contains first, then logical/schema name contains. Ambiguity returns IsError=true with candidates.
- attribute_name, lookup_target, global_optionset_name, and solution_name follow the same Display Name first rule where applicable.

Parameters

Name Type Required Default Description
entity_name string Yes - Logical name (e.g. 'account').
attribute_name string Yes - With prefix ('new_priority') or just name + solution_name to auto-resolve.
attribute_type string Yes - string/memo/integer/bigint/decimal/money/float/boolean/datetime/lookup/customer/picklist/multipicklist/image/file. (immutable on update)
display_name string Yes - Required: create.
solution_name string No "" Auto-resolve prefix when attribute_name has no prefix.
description string No "" -
required_level string No "" None/Recommended/Required. [update: omit=keep]
max_length integer No 0 string 1-4000 (def 100); memo 1-1048576 (def 2000); file KB (def 32768).
min_value number? No - Numeric types: minimum value.
max_value number? No - Numeric types: maximum value.
precision integer No -1 decimal/money/float 0-10 (def 2; money max is 4). [update: omit=keep]
format string No "" string: Text/Email/Url/Phone/TextArea/TickerSymbol/RichText. datetime: DateOnly/DateAndTime. integer: None/Duration/TimeZone/Language/Locale.
behavior string No "" datetime: UserLocal (def)/DateOnly/TimeZoneIndependent. DateOnly forces DateOnly format.
precision_source integer No -1 money: 0=Attribute (def), 1=Organization, 2=Currency.
options string No "" picklist create: JSON array [{"label":"Low","value":100000000}]. Optional 'color' field: {"label":"Low","value":100000000,"color":"#808080"}.
global_optionset_name string No "" picklist create: existing global option set.
lookup_target string No "" lookup create: target entity. Comma-separated = polymorphic.
lookup_relationship_name string No "" lookup: schema name. Auto if empty.
true_label string No "" boolean true label (def 'Yes'). [update: omit=keep]
false_label string No "" boolean false label (def 'No'). [update: omit=keep]
add_options string No "" picklist update: JSON array — options to add. Optional 'color' field: {"label":"New","value":100000003,"color":"#FF0000"}.
update_options string No "" picklist update: JSON array — options to rename. Optional 'color' field: {"label":"NewLabel","value":100000000,"color":"#FF0000"}.
delete_options string No "" picklist update: JSON array of integer values to remove.
is_audit_enabled boolean? No - [update only]
is_valid_for_advanced_find boolean? No - [update only]
schema_name string No "" SchemaName for the new column (e.g. 'devkit_InvoiceLineId'). If provided, used as-is. Create only — ignored on update.

Input Schema

{
  "type": "object",
  "properties": {
    "entity_name": {
      "type": "string",
      "description": "Logical name (e.g. 'account')."
    },
    "attribute_name": {
      "type": "string",
      "description": "With prefix ('new_priority') or just name + solution_name to auto-resolve."
    },
    "attribute_type": {
      "type": "string",
      "description": "string/memo/integer/bigint/decimal/money/float/boolean/datetime/lookup/customer/picklist/multipicklist/image/file. (immutable on update)"
    },
    "display_name": {
      "type": "string",
      "description": "Required: create."
    },
    "solution_name": {
      "type": "string",
      "description": "Auto-resolve prefix when attribute_name has no prefix.",
      "default": ""
    },
    "description": {
      "type": "string",
      "description": "",
      "default": ""
    },
    "required_level": {
      "type": "string",
      "description": "None/Recommended/Required. [update: omit=keep]",
      "default": ""
    },
    "max_length": {
      "type": "integer",
      "description": "string 1-4000 (def 100); memo 1-1048576 (def 2000); file KB (def 32768).",
      "default": 0
    },
    "min_value": {
      "type": "number",
      "description": "Numeric types: minimum value."
    },
    "max_value": {
      "type": "number",
      "description": "Numeric types: maximum value."
    },
    "precision": {
      "type": "integer",
      "description": "decimal/money/float 0-10 (def 2; money max is 4). [update: omit=keep]",
      "default": -1
    },
    "format": {
      "type": "string",
      "description": "string: Text/Email/Url/Phone/TextArea/TickerSymbol/RichText. datetime: DateOnly/DateAndTime. integer: None/Duration/TimeZone/Language/Locale.",
      "default": ""
    },
    "behavior": {
      "type": "string",
      "description": "datetime: UserLocal (def)/DateOnly/TimeZoneIndependent. DateOnly forces DateOnly format.",
      "default": ""
    },
    "precision_source": {
      "type": "integer",
      "description": "money: 0=Attribute (def), 1=Organization, 2=Currency.",
      "default": -1
    },
    "options": {
      "type": "string",
      "description": "picklist create: JSON array [{\"label\":\"Low\",\"value\":100000000}]. Optional 'color' field: {\"label\":\"Low\",\"value\":100000000,\"color\":\"#808080\"}.",
      "default": ""
    },
    "global_optionset_name": {
      "type": "string",
      "description": "picklist create: existing global option set.",
      "default": ""
    },
    "lookup_target": {
      "type": "string",
      "description": "lookup create: target entity. Comma-separated = polymorphic.",
      "default": ""
    },
    "lookup_relationship_name": {
      "type": "string",
      "description": "lookup: schema name. Auto if empty.",
      "default": ""
    },
    "true_label": {
      "type": "string",
      "description": "boolean true label (def 'Yes'). [update: omit=keep]",
      "default": ""
    },
    "false_label": {
      "type": "string",
      "description": "boolean false label (def 'No'). [update: omit=keep]",
      "default": ""
    },
    "add_options": {
      "type": "string",
      "description": "picklist update: JSON array — options to add. Optional 'color' field: {\"label\":\"New\",\"value\":100000003,\"color\":\"#FF0000\"}.",
      "default": ""
    },
    "update_options": {
      "type": "string",
      "description": "picklist update: JSON array — options to rename. Optional 'color' field: {\"label\":\"NewLabel\",\"value\":100000000,\"color\":\"#FF0000\"}.",
      "default": ""
    },
    "delete_options": {
      "type": "string",
      "description": "picklist update: JSON array of integer values to remove.",
      "default": ""
    },
    "is_audit_enabled": {
      "type": "boolean",
      "description": "[update only]"
    },
    "is_valid_for_advanced_find": {
      "type": "boolean",
      "description": "[update only]"
    },
    "schema_name": {
      "type": "string",
      "description": "SchemaName for the new column (e.g. 'devkit_InvoiceLineId'). If provided, used as-is. Create only — ignored on update.",
      "default": ""
    }
  },
  "required": [
    "entity_name",
    "attribute_name",
    "attribute_type",
    "display_name"
  ]
}

Related MCP Resources

Resource URI / URI template MIME type Reason
schema_tools_guide docs://schema_tools_guide text/markdown Inferred from source: Rules, type matrices, and immutable property lists for schema tools. Read this when upsert_table, upsert_column, or upsert_relationship returns an error.

When To Use

  • Create new attribute on an existing table (need attribute_type + display_name)
  • Update mutable metadata, format, required_level, picklist options
  • Add/rename/remove options on an existing picklist via add_options/update_options/delete_options

Notes

  • FUZZY/AMBIGUITY: entity_name resolves Display Name contains first, then logical/schema name contains. Ambiguity returns IsError=true with candidates.
  • FUZZY/AMBIGUITY: attribute_name, lookup_target, global_optionset_name, and solution_name follow the same Display Name first rule where applicable.

Example

{
  "entity_name": "string",
  "attribute_name": "string",
  "attribute_type": "string",
  "display_name": "string"
}

Output

Returns CallToolResult from the MCP server. The response content and structured fields follow the tool implementation and model returned by UpsertColumnTool.upsert_column.

Prompt Examples

  • "Create a required text column on Account with this display name and max length."
  • "Add these options to an existing local picklist and publish the table."
  • "Create a lookup column from this custom table to Contact using the solution prefix."

Home

Get Started

DynamicsCrm.DevKit

Reference

Clone this wiki locally