Dataverse Local MCP

Connect Claude (or any MCP client) to your Microsoft Dataverse / Dynamics 365 environment and work with your data in plain English — query records, run your saved views, explore tables and columns, create and update rows.

• Sign in like you always do — your own Microsoft work account, in your browser, with the same trusted sign-in XrmToolBox uses. Works out of the box: no app registration, no API keys, no admin setup.

• Fast from the second call — your environment's schema and saved views are prefetched and cached locally, so metadata questions answer instantly.

• Full toolbox — OData queries, FetchXML (aggregates and joins), entity CRUD, and metadata discovery in one server.

Guides: Setup · User guide

Getting started

1. Install Node.js 18 or newer if you don't have it.

2. Install the server from the npm install page:

npm install -g dataverse-local-mcp

(Or skip the install and use npx -y dataverse-local-mcp as the command below.)

3. Add it to your MCP client — for Claude Desktop, add this to claude_desktop_config.json, replacing the URL with your environment's:

{
  "mcpServers": {
    "dataverse": {
      "command": "dataverse-local-mcp",
      "args": ["https://yourorg.crm.dynamics.com"]
    }
  }
}

4. Sign in once. The first time a tool runs, your browser opens a Microsoft sign-in — pick your work account for that environment. The token is cached at ~/.dataverse-mcp/token-cache.json, so you won't be asked again until it expires. If the browser signs you in with the wrong account, an account picker is always shown so you can switch.

Try it: ask your MCP client to run the whoami tool — it should return your Dataverse UserId and OrganizationId. Then try "list my saved views on account" or "show me the top 5 accounts by name".

Related MCP server: Dataverse MCP Server

Tools

Data

Schema

Annotations

Environment

Writing safely

Every mutating tool previews by default. Called without confirm: true it describes exactly what would change — naming the resolved record by its primary name — and calls nothing. delete additionally lists the record's current field values, so you can see what is about to be lost.

• One record at a time. update and delete take an id or a where filter, and anything matching more than one record is refused with the candidates listed rather than fanning out.

• Optimistic concurrency by default. Updates and deletes carry the record's ETag, so a write against a record that changed after you read it fails instead of silently overwriting someone else's work. Pass concurrency: false to opt out.

• Payloads are checked before they are sent. Unknown columns, columns not valid for the operation, out-of-range option set values, and unknown @odata.bind navigation properties all fail locally with a message naming the problem — not an opaque platform 400.

• Actions cascade. Much of the real work in Dataverse happens through actions rather than table writes, and their effects reach further than the call suggests. The preview shows the call, not its consequences: those cannot be known without running it.

Errors surface the Dataverse hex code and message, with recognised shapes (privilege denied, duplicate detection, business rule or plugin rejection, concurrency, unknown column) prefixed by a plain-language line. Anything unrecognised passes through verbatim rather than being guessed at.

Resources

The environment's full OData $metadata (CSDL/EDMX) schema is exposed as an MCP resource at dataverse://metadata (application/xml, often several MB).

How the cache works

Right after the stdio handshake the server builds its caches in the background. It never opens a browser at startup: the prefetch uses silent auth only, so with no cached token it waits and retries after your first tool call signs in. Nothing blocks on it — a cold start still works, just slower on the first call.

Everything is keyed by OrganizationId, not environment URL, because URLs change and org ids don't:

~/.dataverse-mcp/
  token-cache.json
  environments/
    index.json                 # host -> organizationId, so a warm start needs no network
    <organizationId>/
      config.json              # url, friendly name, mode, storage, scope, sampling
      schema.json              # cached metadata          } these two follow
      schema.fingerprint       # hash for drift detection } your storage choice
      annotations.md           # your documentation       }
      metadata.xml             # the $metadata resource   } always local:
      saved-queries.json       #                          } large, derived, cheap to refetch

config.json and index.json always stay local — they hold the storage settings themselves, so they can't live inside the backend they describe.

Scope. Every table gets a cheap name-level summary. Full column and relationship detail is cached for all custom tables plus an allowlist of out-of-the-box ones (Field Service and core sales/service by default), capped at maxFullTables. Anything else is fetched lazily and merged the first time a tool touches it.

Row sampling is off by default. Enable it per environment and the cache also records, per column, the fill rate and up to five example values from at most 20 rows — the single most useful signal for tables whose descriptions are blank. It reads real data, so it stays opt-in, and it never samples columns whose type or format suggests personal data unless you explicitly allow it.

Annotations

Dataverse descriptions are frequently blank. The environment's own shape carries most of the meaning; the rest is human knowledge worth accumulating instead of re-deriving every session. Annotations live in plain markdown at environments/<organizationId>/annotations.md — human-editable, diffable, and safe to check into an engagement repo.

## rsm_cipscenariocandidate

Candidate records for capital improvement plan scenario modelling. Populated by
the scenario engine, not by users directly.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: human_

### rsm_scenariotype

Picklist. 1 = replacement, 2 = rehabilitation, 3 = deferral.

_author: ben.vollmer_ · _added: 2026-08-20_ · _confidence: inferred_ · _provenance: human_

Each annotation carries two independent fields. Confidence is confirmed only when a human stated it; anything a model or tool worked out is inferred — which is exactly why annotations are never written back into Dataverse descriptions by default. Provenance is human, preflight, velocity or model, and governs overwrite behaviour on re-scan: a writer may replace its own earlier note freely, and a human replaces anything, but nothing else overwrites. Where a re-scan contradicts a person's note, both are kept and flagged for a human to settle rather than one silently winning.

Tool-authored notes are rendered as blockquotes so you can tell at a glance what came from a person:

### rsm_scenariotype

> No plugins are registered on this column.

_author: preflight_ · _added: 2026-08-20_ · _confidence: confirmed_ · _provenance: preflight_

Sharing. export_annotations writes the file anywhere you like; import_annotations reads one back. Front matter carries the organizationId, and an import into a different org is refused, never merged. Where both sides annotate the same target with different text, both are kept and flagged rather than one silently winning.

Drift. A fingerprint over the schema is captured at cache time. When it moves, each annotation resolves to valid, changed (the type or option set moved underneath the note) or orphaned (the target is gone). A short summary is logged on connect, the specific warning repeats inline in describe_table, and nothing is ever deleted automatically.

Modes. Set explicitly per environment, never inferred from privileges — privileges are usually broader than intent. consumer (the default) keeps annotations local and never writes metadata. maker will additionally allow promoting a confirmed annotation into the Dataverse description itself.

Promoting documentation into Dataverse

If you own an environment's schema, a confirmed annotation can become the real Dataverse description. This is deliberately awkward and the friction should not be reduced for convenience: it needs maker mode, a confirmed annotation (inferences are refused), no unresolved conflict on it, one target per call, and an explicit confirmation after reading the preview.

The written text is prefixed with a [dataverse-mcp] marker plus provenance and date. That marker is the point — without it a promoted note becomes indistinguishable from a human-authored description six months later, and something that read as a reasonable guess starts reading as fact.

Promotion is a metadata write: it creates an unmanaged customization in the active solution layer, which can mask later updates to a managed component, and publishing may be required before the description appears in the UI. The preview says all of this before you confirm, and the tool cannot undo it.

Where your documentation lives

By default everything sits under ~/.dataverse-mcp. Point it somewhere else with set_storage and both the annotations and the metadata cache follow — they always travel together, per environment.

The file-backed kinds are one implementation: an Obsidian vault, a OneDrive sync folder and a Basic Memory directory are all just folders, and git adds a commit step. Each environment gets its own subfolder (dataverse-mcp/<friendlyName>-<orgId prefix>) so a shared vault or repo can hold several without collision.

Notion needs an internal integration token in a NOTION_TOKEN environment variable — set it in your MCP client config, not in a file — and a notionPageId for the parent page, which must be shared with your integration. Each markdown line becomes one paragraph block, so the document round-trips exactly and stays readable and editable in Notion. Because Notion is a document store rather than a file store, the schema cache stays on local disk when Notion is selected; the annotations live in Notion.

Switching storage does not copy what you already have — run export_annotations first if you want to carry it across.

Upgrading from 0.3.x

list_entities and describe_entity are replaced by list_tables and describe_table, which read the new cache and fold in annotations and drift warnings. The 0.3.x cache directory ~/.dataverse-mcp/cache/<host>/ is no longer read and can be deleted; the new cache rebuilds itself on first connect. Your token cache is untouched, so no new sign-in is needed.

Build Spec (for contributors)

Goal

Build a standalone MCP server that talks directly to the Dataverse Web API. Going straight to the Web API keeps the server small and dependency-light, and lets it use the sign-in flow that works most broadly across machines and tenants — including tenants with strict Conditional Access policies. TypeScript, local Node host, no new app registration required.

Why this auth approach

This server uses the same proven auth pattern as XrmToolBox and Microsoft's own XRM Tooling samples: a Microsoft-provided, pre-consented public client with a loopback redirect, driven as a standard MSAL auth-code-plus-PKCE flow. It's the ordinary browser sign-in your tenant already trusts — it runs on every OS, satisfies Conditional Access policies that stop device-code flows, and needs no OS-level broker. Anywhere XrmToolBox connects, this connects.

Client ID: 51f81489-12ee-4a9e-aaae-a2591f45987d
Redirect URI: http://localhost
Authority: https://login.microsoftonline.com/common
Scope: <environmentUrl>/.default

This is a Microsoft multi-tenant sample app with user_impersonation delegated permission, no admin consent required. If XrmToolBox already connects successfully in your tenant, this same client ID is proven to already clear Conditional Access there.

Non-goals for v1

• No custom Entra app registration (use the well-known client ID above)

• No service principal / CI auth (interactive user auth only)

Repo layout

packages/
  core/                    @dataverse-platform/core — shared library, private
    src/
      index.ts             public surface
      auth.ts              MSAL interactive + silent acquisition
      cache.ts             atomic read/write helpers
      paths.ts             ~/.dataverse-mcp layout
      environment.ts       per-environment config, OrganizationId resolution
      dataverseClient.ts   Web API calls
      writes.ts            preview/confirm, validation, single-record resolution
      promotion.ts         annotation -> Dataverse description, maker mode only
      errors.ts            Dataverse error translation
      store.ts             $metadata + saved-view warm cache
      metadata/            schema cache: types, fingerprint, build, sampling
      annotations/         markdown model, store, drift detection
      storage/             backends: directory/git presets, Notion
  mcp-server/              dataverse-local-mcp — published to npm
    src/
      server.ts            MCP wiring
      tools/               tool definitions and formatters
    build.mjs              esbuild bundle (inlines core)
    prepack.mjs            stages README/LICENSE for packing
package.json               npm workspaces root
tsconfig.base.json

The assessment tools (powerpreflight, velocity) join as further packages/*, calling core directly as a library rather than going through the MCP server.

Dependencies

npm install          # installs every workspace
npm run typecheck    # tsc -b across packages
npm run build        # core via tsc, mcp-server bundled via esbuild
npm run clean        # removes dist and tsbuildinfo

Runtime dependencies are @azure/msal-node, @modelcontextprotocol/sdk and open. HTTP calls use Node's built-in global fetch (hence the Node ≥ 18 requirement) — no HTTP client dependency.

Step 1 — Auth module (src/auth.ts)

Acquire and cache a token using acquireTokenInteractive, which spins up its own loopback listener, no manual HTTP server needed.

• Client ID 51f81489-12ee-4a9e-aaae-a2591f45987d, authority https://login.microsoftonline.com/common

• Scope <environmentUrl>/.default

• Token cache persisted to ~/.dataverse-mcp/token-cache.json

• Silent acquisition from cache first, fall back to interactive (system browser opened via the open package; set DATAVERSE_MCP_NO_OPEN=1 to print the URL instead)

• Interactive sign-in always shows the account picker (prompt: select_account) so browser SSO can't silently hand back the wrong account's token

• Concurrent interactive sign-ins are deduped per environment — parallel requests share one browser window

• A silentOnly mode backs the cache prefetch: it throws instead of opening a browser, so background work never interrupts client startup

Step 2 — Dataverse Web API client (src/dataverseClient.ts)

Thin wrapper over the Dataverse Web API (/api/data/v9.2/) sending Authorization: Bearer, OData-MaxVersion: 4.0, OData-Version: 4.0 headers, retrying 429/503 on Retry-After so a bulk metadata build survives service protection limits. Covers whoAmI(), generic get(), record create/update/delete (PATCH sends If-Match: * so updates never silently upsert), FetchXML queries, saved views (savedquery + userquery, following @odata.nextLink), the raw $metadata EDMX, and metadata reads over EntityDefinitions.

Two Dataverse constraints shape the metadata calls: EntityDefinitions rejects $top and $orderby (it accepts $select and $filter), and DisplayName/Description/RequiredLevel come back as objects rather than scalars, so labels are extracted from UserLocalizedLabel.Label. Option sets need a cast — the client tries the EnumAttributeMetadata base cast (one call for picklist, state, status and multiselect) and falls back to the concrete casts where that isn't supported.

Step 3 — MCP server entry (src/server.ts)

Registers the tools listed in the Tools section above plus the dataverse://metadata resource, and kicks off the background cache prefetch after the transport connects. Uses the standard @modelcontextprotocol/sdk Server class with stdio transport, matching how @microsoft/dataverse mcp itself runs. The environment URL is passed as the first CLI argument.

Step 4 — First test

npm run build
node dist/server.js https://yourorg.crm.dynamics.com

Expected: system browser opens once for interactive sign-in, token caches to ~/.dataverse-mcp/token-cache.json, subsequent runs reuse the cached token silently. Confirm success by calling the whoami tool and checking the returned UserId/BusinessUnitId. After the first sign-in, the background prefetch fills ~/.dataverse-mcp/cache/<org-host>/ with metadata.xml, entities.json, and saved-queries.json; later launches serve metadata and saved-view tools from that cache.

Step 5 — Claude Desktop config

{
  "mcpServers": {
    "dataverse": {
      "command": "node",
      "args": ["/full/path/to/DataVerseLocalMCP/dist/server.js", "https://yourorg.crm.dynamics.com"]
    }
  }
}