dataverse-mcp-server

MCP (Model Context Protocol) server for Microsoft Dataverse API with safe-by-default configuration. Works with any Dataverse / Dynamics 365 environment.

Tools

Data operations

| Tool | Description | |------|-------------| | list_entities | List Dataverse tables with optional prefix and solution filters | | list_solutions | List Dataverse solutions (use uniquename to filter list_entities) | | get_entity_schema | Get attributes of a specific table — choice columns carry an option_set summary | | query_records | Query records with OData $filter, $select, $top, $orderby, $expand | | get_record | Get a single record by ID | | create_record | Create a record | | update_record | Update a record | | delete_record | Delete a record (disabled by default, see Safety) |

Note: solution / DATAVERSE_SOLUTION_NAME only scopes list_entities (schema browsing). Data tools (query_records, get_record, create_record, …) keep full access to any table regardless of solution membership — shared tables like account or contact remain reachable.

Schema operations

| Tool | Description | |------|-------------| | create_entity | Create a new table with attributes | | add_attribute | Add a column to an existing table (Choice columns can bind to a Global OptionSet) | | update_attribute | Update column metadata (display name, required level, bounds, …) | | delete_attribute | Delete a column (disabled by default, see Safety) | | get_attribute_dependencies | List CRM components (forms, views, workflows, …) that reference a column — use after delete_attribute fails with 0x8004f01f | | create_relationship | Create relationships between tables (1:N, N:N) | | list_entity_keys | List alternate keys on a table (returns key_attributes, entity_key_index_status, …) | | add_entity_key | Create an alternate key (single or composite) — enables race-safe keyed-PATCH upserts | | delete_entity_key | Delete an alternate key and its supporting unique index (disabled by default, see Safety) |

Dataverse does not allow changing a column's logical name or type. To "rename" or change type: create a new column, migrate data via update_record, then delete_attribute on the old one.

Choice columns: local values or a shared Global OptionSet

A Picklist attribute takes exactly one of two fields. options defines the values inline and produces a Local OptionSet owned by that single column:

{ "logical_name": "contoso_source", "type": "Picklist", "display_name": "Source",
  "options": [ { "label": "Website", "value": 909890000 } ] }

global_option_set instead binds the column to an existing Global OptionSet by name, so several columns across several tables share one list and cannot drift apart:

{ "logical_name": "contoso_source", "type": "Picklist", "display_name": "Source",
  "global_option_set": "contoso_sourceset" }

Supplying both is rejected. That check is not cosmetic: Dataverse itself accepts the pair and then silently ignores the binding, leaving a local copy that looks bound. An unknown set name fails as Global OptionSet not found: '<name>' before anything is created — including in create_entity, which resolves names and validates every attribute before the table exists, so a rejected column cannot leave a half-built table behind.

Verify the result with get_picklist_options: a bound column reports is_global: true and the global set's own metadata_id.

Picklist option management

| Tool | Description | |------|-------------| | get_picklist_options | Read a Local or Global OptionSet — its identity plus [{ value, label }] | | add_picklist_option | Add an option to an existing OptionSet (InsertOptionValue) | | update_picklist_option | Rename an option on an OptionSet (UpdateOptionValue) | | delete_picklist_option | Remove an option from an OptionSet (DeleteOptionValue) |

Picklist tools accept either entity_logical_name + attribute_logical_name (a column) or option_set_name (a Global OptionSet) — the two modes are mutually exclusive. Write operations require Customizer or System Administrator role on the connected service principal. Deleting an option does not update existing records that hold its numeric value — they are left with an orphan integer.

Telling a Global OptionSet from a local copy

get_picklist_options returns the set's identity alongside its options:

{
  "option_set": {
    "name": "fundai_source",
    "is_global": true,                                   // bound to a shared Global OptionSet
    "metadata_id": "ea6ab542-9c2e-f111-88b3-00224805d253"
  },
  "options": [ { "value": 909890000, "label": "Website" }, /* … */ ]
}

is_global is the answer to "does this column reuse an org-wide list, or does it own a private copy?" — matching values prove nothing on their own, and a column with a local set reports an auto-generated name like opportunity_prioritycode with is_global: false. To confirm which global set a column is bound to, compare its metadata_id against the one returned by get_picklist_options { option_set_name: … }.

The lookup covers Choice, Status, State and MultiSelect columns, so statecode / statuscode can be read the same way as a custom choice column.

get_entity_schema reports the same identity per column as a compact option_set summary with an option_count instead of the values themselves — read the values for a single column with get_picklist_options:

{
  "LogicalName": "fundai_source",
  "AttributeType": "Picklist",
  "option_set": { "name": "fundai_source", "is_global": true, "metadata_id": "ea6ab542-…", "option_count": 6 }
}

Actions & functions

| Tool | Description | |------|-------------| | invoke_action | Invoke a Web API action (POST), bound or unbound — for operations outside plain CRUD (e.g. PublishDuplicateRule, QualifyLead) | | invoke_function | Invoke a Web API function (GET), bound or unbound — read-only operations exposed as functions (e.g. WhoAmI) |

Pass entity_set + id for a bound call (POST /<entity_set>(<id>)/Microsoft.Dynamics.CRM.<name>); omit both for an unbound call (POST /<name>). For invoke_action, parameters is the JSON request body; for invoke_function, parameters is inlined as OData function arguments. Bare operation names are namespaced automatically for bound calls — pass a fully-qualified name to override.

Examples:

// Publish a draft duplicate-detection rule.
// PublishDuplicateRule is a BOUND action on duplicaterule (returns an async job).
invoke_action({ name: "PublishDuplicateRule", entity_set: "duplicaterules", id: "<guid>" })

// Unpublish is an UNBOUND action taking DuplicateRuleId — note the asymmetry.
invoke_action({ name: "UnpublishDuplicateRule", parameters: { DuplicateRuleId: "<guid>" } })

// Qualify a lead into Account/Contact/Opportunity (bound action on lead).
invoke_action({ name: "QualifyLead", entity_set: "leads", id: "<guid>",
                parameters: { CreateAccount: true, CreateContact: true, CreateOpportunity: true, Status: 3 } })

Whether an operation is bound or unbound is defined in the Web API $metadata, not by intuition — e.g. PublishDuplicateRule is bound but UnpublishDuplicateRule is unbound. Check $metadata (look for IsBound="true" and the binding Parameter) if a call returns 404 "Resource not found for the segment".

⚠️ invoke_action can perform arbitrary mutating operations. It is currently ungated by design; capability-based access control (a safe-by-default policy gating writes/actions) is tracked separately in #45 / #46. invoke_function is read-only.

Quick start (no clone)

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": ["-y", "@rededis/dataverse-mcp-server"]
    }
  }
}

Create a .env file next to it with the four required variables (see Environment variables below) and restart your MCP client. The -y flag tells npx to auto-confirm the package install.

Setup

Environment variables

DATAVERSE_TENANT_ID=your-azure-tenant-id
DATAVERSE_CLIENT_ID=your-app-registration-client-id
DATAVERSE_CLIENT_SECRET=your-client-secret
DATAVERSE_RESOURCE_URL=https://your-org.crm.dynamics.com
DATAVERSE_ENTITY_PREFIX=contoso_          # optional, default prefix filter for list_entities
DATAVERSE_SOLUTION_NAME=MySolution        # optional, default solution unique name for list_entities
DATAVERSE_ALLOW_DELETE=true               # optional, enable delete operations (disabled by default)

Azure App Registration

1. Register an app in Azure AD
2. Add API permission: Dynamics CRM > user_impersonation (or Application permissions)
3. Create a client secret
4. Grant the app a security role in Dataverse (e.g. System Administrator for full access)

Build

npm install
npm run build

Claude Code configuration (local build)

If you cloned the repo instead of using npx:

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Create a .env file with your credentials (see .env.example).

Safety

Destructive operations are disabled by default to prevent accidental data loss. All four delete tools are gated behind the same DATAVERSE_ALLOW_DELETE=true flag:

• delete_record — removes a row and all its data
• delete_attribute — removes a column along with ALL values across every record (no recovery short of a full environment restore)
• delete_picklist_option — removes an option from an OptionSet; records that hold the option's integer value are left with an orphan number (no label in UI, broken reports)
• delete_entity_key — drops an alternate key and its supporting unique index; any keyed-PATCH upsert flows relying on it stop working

When the flag is off, each tool registers as a stub that returns an instructional error instead of performing the delete. To enable, add DATAVERSE_ALLOW_DELETE=true to your .env file and restart the MCP server.

License

MIT