mcp_upsert_relationship

Summary

Field	Value
Tool name	upsert_relationship
MCP title	Create, update, or delete Dataverse relationships
Category	advanced
Implementation	DynamicsCrm.DevKit.Cli/Mcp/Tools/UpsertRelationshipTool.cs
Estimated token count	~848 tokens (tools/list tool JSON, o200k_base, measured 2026-06-18)
Last verified	2026-06-18

MCP Tool Description (Exact)

Dataverse relationships (1:N, N:N) + polymorphic lookup targets. Required:
- create_1n: referenced_entity + referencing_entity + solution_name (auto-creates lookup column)
- create_nn: entity1 + entity2 + solution_name (auto-creates intersect entity)
- update: relationship_name (cascade/menu/hierarchy)
- delete: relationship_name
- add_target: entity_name + attribute_name + referenced_entity + solution_name
- remove_target: entity_name + attribute_name + referenced_entity (deletes data permanently)

is_hierarchical: only for self-referential 1:N (referenced=referencing), max 1/entity.
Cascade presets: Parental (all Cascade) | Referential (NoCascade + RemoveLink on delete) | ReferentialRestrictDelete (NoCascade + Restrict on delete).
Cascade types: Cascade | NoCascade | RemoveLink | Restrict | Active | UserOwned.
See docs://schema_tools_guide.

WHEN TO USE:
- Create 1:N (with auto lookup column) or N:N (with intersect entity)
- Update cascade behavior, associated menu, or hierarchy flag
- Add / remove a target on a polymorphic lookup (e.g. customer → account, contact, custom)
- Inspect relationship_name first via get_tables before update/delete

FUZZY/AMBIGUITY:
- entity and field inputs resolve Display Name contains first, then logical/schema name contains. solution_name uses the shared Display Name first solution resolver. Ambiguity returns IsError=true.

Parameters

Name	Type	Required	Default	Description
action	string	No	""	create_1n / create_nn / update / delete / add_target / remove_target.
relationship_name	string	No	""	Schema name. Required: update/delete. Auto-generated on create.
referenced_entity	string	No	""	Parent (1:N create, add/remove target).
referencing_entity	string	No	""	Child (1:N create).
entity1	string	No	""	First entity for N:N.
entity2	string	No	""	Second entity for N:N.
intersect_entity_name	string	No	""	N:N intersect entity. Auto if empty.
entity_name	string	No	""	Entity with polymorphic lookup (add/remove target).
attribute_name	string	No	""	Polymorphic lookup logical name.
cascade_preset	string	No	""	Parental / Referential / ReferentialRestrictDelete.
cascade_assign	string	No	""	Override cascade Assign behavior.
cascade_delete	string	No	""	Override cascade Delete behavior.
cascade_merge	string	No	""	Override cascade Merge behavior.
cascade_reparent	string	No	""	Override cascade Reparent behavior.
cascade_share	string	No	""	Override cascade Share behavior.
cascade_unshare	string	No	""	Override cascade Unshare behavior.
menu_behavior	string	No	""	UseCollectionName / UseLabel / DoNotDisplay.
menu_group	string	No	""	Details / Sales / Service / Marketing.
menu_order	integer	No	10000	-
lookup_display_name	string	No	""	1:N create only.
solution_name	string	No	""	Required: create_1n, create_nn, add_target.
is_hierarchical	boolean	No	false	Self-referential 1:N (create_1n/update). 1 per entity, referenced=referencing.

Input Schema

{
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "description": "create_1n / create_nn / update / delete / add_target / remove_target.",
      "default": ""
    },
    "relationship_name": {
      "type": "string",
      "description": "Schema name. Required: update/delete. Auto-generated on create.",
      "default": ""
    },
    "referenced_entity": {
      "type": "string",
      "description": "Parent (1:N create, add/remove target).",
      "default": ""
    },
    "referencing_entity": {
      "type": "string",
      "description": "Child (1:N create).",
      "default": ""
    },
    "entity1": {
      "type": "string",
      "description": "First entity for N:N.",
      "default": ""
    },
    "entity2": {
      "type": "string",
      "description": "Second entity for N:N.",
      "default": ""
    },
    "intersect_entity_name": {
      "type": "string",
      "description": "N:N intersect entity. Auto if empty.",
      "default": ""
    },
    "entity_name": {
      "type": "string",
      "description": "Entity with polymorphic lookup (add/remove target).",
      "default": ""
    },
    "attribute_name": {
      "type": "string",
      "description": "Polymorphic lookup logical name.",
      "default": ""
    },
    "cascade_preset": {
      "type": "string",
      "description": "Parental / Referential / ReferentialRestrictDelete.",
      "default": ""
    },
    "cascade_assign": {
      "type": "string",
      "description": "Override cascade Assign behavior.",
      "default": ""
    },
    "cascade_delete": {
      "type": "string",
      "description": "Override cascade Delete behavior.",
      "default": ""
    },
    "cascade_merge": {
      "type": "string",
      "description": "Override cascade Merge behavior.",
      "default": ""
    },
    "cascade_reparent": {
      "type": "string",
      "description": "Override cascade Reparent behavior.",
      "default": ""
    },
    "cascade_share": {
      "type": "string",
      "description": "Override cascade Share behavior.",
      "default": ""
    },
    "cascade_unshare": {
      "type": "string",
      "description": "Override cascade Unshare behavior.",
      "default": ""
    },
    "menu_behavior": {
      "type": "string",
      "description": "UseCollectionName / UseLabel / DoNotDisplay.",
      "default": ""
    },
    "menu_group": {
      "type": "string",
      "description": "Details / Sales / Service / Marketing.",
      "default": ""
    },
    "menu_order": {
      "type": "integer",
      "description": "",
      "default": 10000
    },
    "lookup_display_name": {
      "type": "string",
      "description": "1:N create only.",
      "default": ""
    },
    "solution_name": {
      "type": "string",
      "description": "Required: create_1n, create_nn, add_target.",
      "default": ""
    },
    "is_hierarchical": {
      "type": "boolean",
      "description": "Self-referential 1:N (create_1n/update). 1 per entity, referenced=referencing.",
      "default": false
    }
  },
  "required": []
}

Related MCP Resources

Resource	URI / URI template	MIME type	Reason
schema_tools_guide	docs://schema_tools_guide	text/markdown	Mentioned in MCP metadata: 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 1:N (with auto lookup column) or N:N (with intersect entity)
• Update cascade behavior, associated menu, or hierarchy flag
• Add / remove a target on a polymorphic lookup (e.g. customer → account, contact, custom)
• Inspect relationship_name first via get_tables before update/delete

Notes

• FUZZY/AMBIGUITY: entity and field inputs resolve Display Name contains first, then logical/schema name contains. solution_name uses the shared Display Name first solution resolver. Ambiguity returns IsError=true.

Example

{
  "action": "string"
}

Output

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

Prompt Examples

• "Create a one-to-many relationship from Account to this custom child table."
• "Update this relationship to use referential restrict delete behavior."
• "Add this table as a new target for the polymorphic lookup field."