# dataverse-mcp-server

[![npm version](https://img.shields.io/npm/v/@rededis/dataverse-mcp-server.svg)](https://www.npmjs.com/package/@rededis/dataverse-mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@rededis/dataverse-mcp-server.svg)](https://www.npmjs.com/package/@rededis/dataverse-mcp-server)
[![CI](https://github.com/rededis/dataverse-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/rededis/dataverse-mcp-server/actions/workflows/ci.yml)
[![Node.js](https://img.shields.io/node/v/@rededis/dataverse-mcp-server.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6.svg)](https://www.typescriptlang.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

MCP (Model Context Protocol) server for Microsoft Dataverse API with [safe-by-default](#safety) 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](#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](#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](#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:

```jsonc
{ "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:

```jsonc
{ "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:

```jsonc
{
  "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`:

```jsonc
{
  "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:

```jsonc
// 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](https://github.com/rededis/dataverse-mcp-server/issues/45). `invoke_function` is read-only.

## Quick start (no clone)

Add to `.mcp.json` in your project root:

```json
{
  "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](#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)
DATAVERSE_REQUEST_TIMEOUT_MS=30000        # optional, per-request timeout in ms for Dataverse and token calls (default 30000, max 120000)
DATAVERSE_MAX_CONCURRENCY=8               # optional, requests sent to Dataverse at once (default 8, 1 to 100)
DATAVERSE_MAX_QUEUE_LENGTH=100            # optional, requests that may wait for a free slot (default 100, 0 to 10000)
DATAVERSE_MAX_QUEUE_WAIT_MS=10000         # optional, longest wait for a free slot in ms (default 10000, max 120000)
DATAVERSE_MAX_ATTEMPTS=3                  # optional, times a throttled request is sent, the first try included (default 3, 1 to 10)
DATAVERSE_MAX_RETRY_WAIT_MS=15000         # optional, longest wait on throttling per request in ms (default 15000, max 120000)
```

`DATAVERSE_REQUEST_TIMEOUT_MS` bounds how long a tool call waits for Dataverse. Dataverse itself cancels any operation after 2 minutes, hence the maximum. Schema changes such as `create_entity` with many columns can take longer than the 30-second default. When that happens the tool reports a timeout, but Dataverse still finishes the change, so check before retrying, or raise the value.

#### Service protection limits

Dataverse throttles each user with [service protection limits](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/api-limits) and answers `429 Too Many Requests` when one is reached. Parallel tool calls can reach them even from one machine. The server handles this in two ways, and all five `DATAVERSE_MAX_*` variables above are optional:

- **It limits what it sends.** At most `DATAVERSE_MAX_CONCURRENCY` requests are in flight; the rest wait in arrival order. A request is turned away with a "Dataverse is busy" error when `DATAVERSE_MAX_QUEUE_LENGTH` requests are already waiting, or when it has waited `DATAVERSE_MAX_QUEUE_WAIT_MS` without getting a slot.
- **It retries a 429.** The server waits for as long as the `Retry-After` header says, then resends, up to `DATAVERSE_MAX_ATTEMPTS` sends in total. While it waits, no other request is sent either, because Dataverse extends the wait for a client that keeps sending. Other requests are held back for the wait Dataverse asked for, but never longer than `DATAVERSE_MAX_RETRY_WAIT_MS`: a `Retry-After` of several minutes fails the call that received it and does not stop the rest for that long. If the waits of one request would add up to more than `DATAVERSE_MAX_RETRY_WAIT_MS`, the tool call fails at once with an error that says in how many seconds to retry.

With the defaults, these limits add at most 25 seconds of waiting to one request: 10 in the queue and 15 on throttling. With one request at the default 30-second timeout that makes 55 seconds, inside the 60 seconds a client built on the MCP TypeScript SDK waits for an answer unless configured otherwise. That figure assumes a 429 arrives promptly, and it does not always: in a live test, heavy requests that hit the execution-time limit were answered with 429 only after 28 to 75 seconds. The bound that holds whatever happens is 115 seconds: the 25 seconds of waiting plus three sends that each take the whole request timeout. A request that slow is cut off by `DATAVERSE_REQUEST_TIMEOUT_MS` first and reported as a timeout, not retried. A tool that sends several requests can take that long for each of them. If you raise the waits or `DATAVERSE_REQUEST_TIMEOUT_MS`, raise the tool-call timeout of your MCP client to match.

The concurrency limit alone does not prevent throttling, since Dataverse also limits combined execution time. The defaults are deliberately conservative choices of this server, not values published by Microsoft. A value that is set but out of range is reported through `dataverse_setup`, like a missing variable.

### 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

```bash
npm install
npm run build
```

### Claude Code configuration (local build)

If you cloned the repo instead of using `npx`:

```json
{
  "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