Skip to main content
Glama
dataverse-mcp-server

dataverse-mcp-server

dataverse-mcp-server

CI License: MIT

An MCP server that gives AI agents (Claude Desktop, VS Code with GitHub Copilot, or any MCP client) scoped access to Microsoft Dataverse and Dynamics 365 CE data through the Web API.

It is read-only unless you say otherwise, it caps how many rows a single call can return, and it only ever talks to the endpoints it was written for.

Why

Most Dynamics 365 questions that end up as a ticket are lookups: "which open opportunities does this account have", "what is the status reason on this case", "who owns these leads". An agent with the right tools can answer them in seconds, but handing it a raw HTTP client and a service principal is a bad idea. This server sits in between:

  • the agent gets a handful of well-described tools instead of the whole Web API surface;

  • requests are built from validated table names, column names and ids, so a tool call cannot be turned into a call to an arbitrary URL;

  • results come back shaped for a model to read: choice labels and lookup names next to the raw values, no OData bookkeeping, and an explicit flag when a result was truncated;

  • Dataverse errors are translated into messages the agent can act on (missing privilege, unknown column, throttling) instead of a stack trace.

Related MCP server: mcp-dynamics-365

Architecture

flowchart LR
    subgraph Client["MCP client"]
        A[Claude Desktop / VS Code]
    end
    subgraph Server["dataverse-mcp (stdio)"]
        T[Tools, resource, prompt<br/>server.py]
        V[Validation and shaping<br/>odata.py]
        C[Web API client<br/>client.py]
        M[Token provider<br/>auth.py]
    end
    E[(Entra ID)]
    D[(Dataverse Web API v9.2)]

    A -- JSON-RPC over stdio --> T
    T --> V --> C
    C --> M
    M -- client credentials --> E
    C -- HTTPS + bearer token --> D

The server runs as a child process of the MCP client and speaks JSON-RPC over stdin/stdout. Authentication uses the client-credentials flow, so the agent acts as a Dataverse application user and gets exactly the privileges of the security role you assign to it.

Tools

Tool

Writes

Description

list_tables

no

Tables available to the connection. Customizable, non-intersect tables by default; search filters by name, include_system shows everything.

describe_table

no

Entity set, primary id/name and every readable column with its type, whether it is required, and for lookups the _x_value name to use in queries.

query_records

no

OData query with select, filter, orderby and top. Row count is capped; more_records tells the agent when there was more.

get_record

no

One row by id. Accepts ids with or without braces.

create_record

yes

Create a row, returns its id. Lookups are set with navprop@odata.bind.

update_record

yes

Update columns on an existing row. Never creates a row by accident (see below).

Also exposed:

  • Resource dataverse://connection: environment URL, write mode, row limits and the identity (WhoAmI) the server is running as. Useful for an agent to check what it is connected to.

  • Prompt explore_table: describes a table and pulls a small sample, a quick way to get oriented in an unfamiliar org.

Setup

1. Register an app in Entra ID

  1. In the Azure portal, go to Microsoft Entra ID > App registrations > New registration. Single tenant, no redirect URI.

  2. Under Certificates & secrets, create a client secret and copy its value.

  3. Note the Application (client) ID and Directory (tenant) ID.

No API permissions need to be granted on the app registration. Access to Dataverse is controlled entirely by the application user in the next step.

2. Create the Dataverse application user

  1. Open the Power Platform admin center, select the environment, then Settings > Users + permissions > Application users > New app user.

  2. Pick the app registration from step 1 and a business unit.

  3. Assign a security role.

Give it the smallest role that does the job. A good starting point is a copy of a read-only role with Organization-level Read on only the tables the agent should see. If you enable writes, add Create and Write on those specific tables, and leave Delete, Assign and Share off. Avoid System Administrator and System Customizer: the server's own guardrails are a second line of defense, not a substitute for Dataverse security.

3. Install and configure

Requires Python 3.11 or later.

git clone https://github.com/mateusmirandaia/dataverse-mcp-server.git
cd dataverse-mcp-server
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env           # then fill in the values

Variable

Default

Notes

DATAVERSE_URL

Environment root, e.g. https://yourorg.crm.dynamics.com

DATAVERSE_TENANT_ID

Directory (tenant) ID

DATAVERSE_CLIENT_ID

Application (client) ID

DATAVERSE_CLIENT_SECRET

Client secret value

DATAVERSE_ALLOW_WRITES

false

Exposes create_record and update_record when true

DATAVERSE_DEFAULT_TOP

25

Rows returned when the agent does not ask for a number

DATAVERSE_MAX_TOP

200

Hard ceiling per call (Dataverse itself stops at 5000)

DATAVERSE_TIMEOUT_SECONDS

30

Per-request timeout

Settings are read from the environment first, then from .env in the working directory. In MCP client configs it is usually simpler to pass them as env, as shown below.

4. Connect a client

Claude Desktop: edit claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "dataverse": {
      "command": "/path/to/dataverse-mcp-server/.venv/bin/dataverse-mcp",
      "env": {
        "DATAVERSE_URL": "https://yourorg.crm.dynamics.com",
        "DATAVERSE_TENANT_ID": "00000000-0000-0000-0000-000000000000",
        "DATAVERSE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "DATAVERSE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

On Windows the command is C:\\path\\to\\dataverse-mcp-server\\.venv\\Scripts\\dataverse-mcp.exe.

VS Code (GitHub Copilot agent mode): add .vscode/mcp.json to your workspace. Using an input keeps the secret out of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "dataverse-secret",
      "description": "Dataverse client secret",
      "password": true
    }
  ],
  "servers": {
    "dataverse": {
      "type": "stdio",
      "command": "${workspaceFolder}/.venv/bin/dataverse-mcp",
      "env": {
        "DATAVERSE_URL": "https://yourorg.crm.dynamics.com",
        "DATAVERSE_TENANT_ID": "00000000-0000-0000-0000-000000000000",
        "DATAVERSE_CLIENT_ID": "00000000-0000-0000-0000-000000000000",
        "DATAVERSE_CLIENT_SECRET": "${input:dataverse-secret}"
      }
    }
  }
}

Then ask something like "List the five most recently created active accounts with their primary contact" and watch it go through list_tables, describe_table and query_records.

Safety design

Read-only by default. An agent that can only read can at worst show you something it should not have (which the security role already decides). An agent that can write can corrupt data at machine speed, trigger plugins and Power Automate flows, and send emails through workflows. Write tools are not registered at all unless DATAVERSE_ALLOW_WRITES=true, so the model never sees them, and the client refuses writes independently of the tool layer. When you do enable writes, the tools carry MCP annotations (destructiveHint on update) so clients can ask for confirmation.

Row limits. Every query is capped at DATAVERSE_MAX_TOP regardless of what the agent asks for. The cap is applied through Prefer: odata.maxpagesize rather than $top, because Dataverse omits @odata.nextLink when $top is present, and without it there is no way to tell the agent its result was incomplete. The server never follows nextLink on its own; it reports more_records: true and the agent is told to narrow the filter. This keeps context windows and your API request allocation under control.

No arbitrary URLs. Tools take table logical names, column names and GUIDs, all validated against a strict pattern before anything is sent. The entity set name is resolved from metadata, not trusted from input. Filters travel as an encoded query-string value, so they cannot add query options or change the path. Lookup binds on writes must look like /entityset(guid).

No accidental upserts. A PATCH to Dataverse creates the record if the id does not exist. A hallucinated id would silently produce a new row, so update_record always sends If-Match: * and gets a 404 instead.

Secrets. The client secret is held as a SecretStr and never logged. Tokens are cached in memory by MSAL and refreshed shortly before expiry; nothing is written to disk.

Development

pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest

Tests mock the Web API with respx and drive the server through the MCP SDK's in-memory client, so they run offline and need no Dataverse environment. They cover query building and validation, top clamping, the write guard, error mapping (including throttling and timeouts), token acquisition and the tool contract as a client sees it.

Layout:

src/dataverse_mcp/
  server.py   tool, resource and prompt definitions; CLI entry point
  client.py   async Web API client, metadata cache, error mapping
  odata.py    validation and query helpers, record shaping
  auth.py     MSAL client-credentials token provider
  config.py   settings (pydantic-settings)
  errors.py   exception types shown to the agent

Roadmap

  • FetchXML tool for aggregates and joins that OData handles poorly

  • Choice (option set) values in describe_table, so agents can filter by value without guessing

  • Certificate credentials and managed identity as alternatives to a client secret

  • Table allow-list (DATAVERSE_TABLES=account,contact,...) on top of the security role

  • Bounded retry on 429 using Retry-After

  • Streamable HTTP transport for running as a shared service

  • Optional audit log of write operations

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to query, inspect, and manage Microsoft Dataverse records, metadata, schema, forms, views, and Power Platform environments via the Dataverse OData Web API.
      97
      74 PyPI
      3
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to perform CRUD operations, query data, fetch schemas, and execute custom operations on Microsoft Dynamics 365 CRM entities.
      10
      24 npm
      2
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables direct interaction with Microsoft Dataverse from Claude Desktop, supporting full CRUD, bulk operations, FetchXML queries, actions, and metadata discovery.
      20
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables interaction with Microsoft Dataverse and Dynamics 365 data through natural language, including CRUD operations, metadata exploration, and saved views.
      MIT