Dataverse CLI (Preview)

A command-line tool for Microsoft Dataverse that provides authentication management, environment operations, data access, dynamic API discovery/invocation, ERP utilities, and an MCP (Model Context Protocol) server for AI assistant integration.

Installation

Global Installation

npm install -g @microsoft/dataverse

Use with npx (No Installation Required)

npx @microsoft/dataverse <command> [options]

Prerequisites

Before you can use the Dataverse MCP server, the following setup steps must be completed by your administrators:

1. Azure Tenant Admin: Grant Admin Consent

An Azure tenant administrator must grant admin consent for the Dataverse MCP CLI tool application.

Steps:

1. Navigate to: https://login.microsoftonline.com/{your-tenant-id}/adminconsent?client_id=0c412cc3-0dd6-449b-987f-05b053db9457
   • Replace {your-tenant-id} with your actual Azure tenant ID
2. Sign in as an Azure tenant administrator
3. Review and grant the requested permissions

2. Dataverse Admin: Enable MCP Server

A Dataverse organization administrator must enable the MCP server feature for your environment.

Resources:

• Enable Dataverse MCP (Production)
• Enable Dataverse MCP (Preview)

3. Dataverse Admin: Allow the MCP CLI Tool

A Dataverse organization administrator must add the Dataverse MCP CLI tool to the allowed client applications list.

Steps:

1. Follow the instructions at: Configure MCP Client List
2. Add the application with App ID: 0c412cc3-0dd6-449b-987f-05b053db9457
   • This will appear as "Dataverse MCP CLI tool" in the UI

Note: All three prerequisite steps must be completed before you can successfully authenticate and connect to your Dataverse environment.

Automatic Update Checking

The CLI automatically checks for new versions on npmjs.com when you run any command. If a newer version is available, you'll see a notification prompting you to update.

Features

• Profile-based authentication compatible with PAC CLI auth profiles
• Dataverse environment commands (org / env)
• Dataverse data commands for query/get/create/update/upsert/delete/count plus associate/disassociate
• Dynamic api commands for Dataverse custom APIs and ERP invocable service endpoints
• ERP batch job management for linked Finance & Operations environments
• MCP server support for Claude Desktop and other MCP clients
• --json output on supported commands for scripting

Command Reference

| Command | Description | |---------|-------------| | auth create | Create a new authentication profile | | auth select | Select the active authentication profile | | auth list | List all authentication profiles | | auth who | Show the current authentication profile | | auth remove | Remove an authentication profile | | org who | Show current organization and user info | | org list | List all accessible environments | | api list | List discoverable APIs | | api describe | Describe an API | | api invoke | Invoke an API by name | | api request | Send an authenticated HTTP request | | erp batch list | List Finance & Operations batch jobs | | erp batch cancel | Cancel a Finance & Operations batch job | | data query | Execute an OData or FetchXML query | | data get | Retrieve a single record by ID or alternate key | | data create | Create a new record | | data update | Update an existing record | | data upsert | Create or update a record by alternate key | | data delete | Delete a record | | data associate | Link two records via a relationship | | data disassociate | Remove a relationship between two records | | data count | Count records in a table | | mcp | Start MCP server for Dataverse | | mcp allow | Allow an app as MCP client in current environment |

Detailed Command Guide

install - Install a Specific Version

Install a specific version of the Dataverse CLI, or update to the latest version.

Usage

Install latest version:

dataverse install latest

Install specific version:

dataverse install 0.1.0

With npx:

npx @microsoft/dataverse install latest
npx @microsoft/dataverse install 0.1.0

This command works whether you have a global installation or are using npx. It will automatically detect your installation method and install accordingly.

auth - Authentication Profile Management

Manage authentication profiles for connecting to Dataverse environments.

auth create - Create a New Profile

# Interactive authentication (opens browser or system dialog)
dataverse auth create --environment https://myorg.crm.dynamics.com

# Named profile
dataverse auth create --environment https://myorg.crm.dynamics.com --name prod

# Device code flow (for environments without a browser)
dataverse auth create --environment https://myorg.crm.dynamics.com --deviceCode

# Service principal with client secret
dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId>

# Custom Entra app client ID (use your own app registration instead of the default)
dataverse auth create --environment https://myorg.crm.dynamics.com --clientid <your-app-guid>

Run dataverse auth create --help for all options including certificate auth, managed identity, and federated auth.

auth select - Switch Active Profile

# Interactive picker (arrow keys, type to filter)
dataverse auth select

# By index or name
dataverse auth select --index 1
dataverse auth select --name prod

auth list - List All Profiles

dataverse auth list
dataverse auth list --json

auth who - Show Current Profile

dataverse auth who
dataverse auth who --json

auth remove - Remove a Profile

# Remove by 1-based index (from 'auth list')
dataverse auth remove --index 1

# Remove by name
dataverse auth remove --name prod

# Remove all profiles
dataverse auth remove --all

org (or env) - Environment Operations

Query Dataverse environments using the current authentication profile.

org who - Current Organization Info

dataverse org who
dataverse org who --environment https://myorg.crm.dynamics.com
dataverse org who --json

org list - List Accessible Environments

dataverse org list
dataverse org list --filter contoso
dataverse org list --json

api - Dataverse and ERP API Commands

Discover, describe, invoke, and make raw authenticated requests to Dataverse custom APIs and ERP invocable service endpoints.

api list - List Discoverable APIs

dataverse api list
dataverse api list invoice --target dataverse
dataverse api list --target erp GetUserSessionInfo
dataverse api list --target erp --service-group UserSessionService --service AifUserSessionService

Results show the API identity, friendly name, kind, and description when available.

api describe - Show API Metadata

dataverse api describe sample_CustomAPIExample
dataverse api describe msdyn_DoesKBExist
dataverse api describe GetUserSessionInfo --target erp --service-group UserSessionService --service AifUserSessionService

For Dataverse custom APIs, the output includes request parameter and response property descriptions when the metadata provides them.

api invoke - Invoke an API by Name

# Dataverse function
dataverse api invoke CCaaS_GetPresence ApiVersion=1.0

# Dataverse action with spaces in a parameter value
dataverse api invoke AISummarize "Text=The customer reported intermittent login failures..."

# Preserve raw JSON output
dataverse api invoke AISummarize "Text=The customer reported intermittent login failures..." --json

# ERP custom service
dataverse api invoke GetUserSessionInfo --target erp --service-group UserSessionService --service AifUserSessionService

Use name=value syntax for parameters. If a value contains spaces, quote the whole token. Some Dataverse APIs accept a string parameter whose contents are themselves JSON; in that case, pass JSON text as the value using your shell's normal quoting/escaping rules.

By default, api invoke renders JSON responses in a friendly text format that keeps output property names. Use --json to preserve the raw JSON payload.

api request - Send a Raw Authenticated Request

dataverse api request --target dataverse --path /api/data/v9.2/sample_CustomAPIExample --body "{\"Input\":\"value\"}"
dataverse api request --target erp --path /api/services/UserSessionService/AifUserSessionService/GetUserSessionInfo --body "{}"

mcp - MCP Server for Dataverse

Starts an MCP (Model Context Protocol) server that connects to your Dataverse environment, enabling AI assistants like Claude to interact with your Dataverse data.

Usage

dataverse mcp <orgUrl> [options]

Arguments:

• <orgUrl> - Your Dataverse organization URL (e.g., https://myorg.crm.dynamics.com)

Options:

• --validate - Validate MCP endpoints and authentication setup without starting the server
• --log-level <level> - Set logging level: Trace, Debug, Information, Warning, Error, Critical (default: Warning)
• --log-file - Enable logging to a file in the temp directory
• --preview - Use preview MCP endpoint (api/mcp_preview instead of api/mcp)

Examples

Validate setup (recommended first step):

dataverse mcp https://myorg.crm.dynamics.com --validate

This will test both the GA and Preview endpoints and verify that:

• Authentication is working correctly
• The MCP server is enabled
• The MCP CLI tool is in the allowed applications list

If validation fails, the output will provide specific guidance on which prerequisite steps need to be completed.

Basic usage with stdio transport:

dataverse mcp https://myorg.crm.dynamics.com

With npx:

npx @microsoft/dataverse mcp https://myorg.crm.dynamics.com

Use preview endpoint:

dataverse mcp https://myorg.crm.dynamics.com --preview

Enable debug logging:

dataverse mcp https://myorg.crm.dynamics.com --log-level Debug

Enable file logging (useful for troubleshooting):

dataverse mcp https://myorg.crm.dynamics.com --log-file

mcp allow - Allow an MCP Client Application

Ensures an Azure AD application is in the Dataverse MCP allowed clients list for the current profile's environment. This is an alternative to the manual admin step in Prerequisites.

dataverse mcp allow 0c412cc3-0dd6-449b-987f-05b053db9457

Note: Requires the authenticated user to have Dataverse admin permissions on the target environment.

erp batch - Finance & Operations Batch Jobs

Manage batch jobs on the Finance & Operations instance linked to your Dataverse environment. Requires an auth profile connected to a Dataverse environment with a linked F&O instance.

erp batch list - List Batch Jobs

# List all batch jobs
dataverse erp batch list

# Filter by status
dataverse erp batch list --status Waiting
dataverse erp batch list --status executing --top 20

Options:

| Option | Description | |--------|-------------| | --status <value> | Filter by status: Waiting, Executing, Ended, Error, Cancelling, Withhold | | --top <n> | Return at most n jobs (positive integer) |

erp batch cancel - Cancel a Batch Job

dataverse erp batch cancel <recid>

Cancels the batch job with the given RecId (use erp batch list to find IDs).

data - Dataverse Data Operations

Use the data namespace for Dataverse table/entity operations:

dataverse data query account --select name,revenue --top 5
dataverse data get account <guid>
dataverse data create account --data "{\"name\":\"Contoso\"}"
dataverse data update account <guid> --data "{\"name\":\"Updated Contoso\"}"
dataverse data upsert account accountnumber=ACC-100 --data "{\"name\":\"Contoso\"}"
dataverse data delete account <guid>
dataverse data count account

Run dataverse data <subcommand> --help for full option details on query, get, create, update, upsert, delete, associate, disassociate, and count.

Using with Claude Desktop

To use the Dataverse MCP server with Claude Desktop, add it to your MCP configuration.

Quick Setup

claude mcp add dataverse -t stdio -- npx -y @microsoft/dataverse mcp https://yourorg.crm.dynamics.com

Manual Configuration

Edit your Claude Desktop MCP configuration file:

Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": ["-y", "@microsoft/dataverse", "mcp", "https://yourorg.crm.dynamics.com"],
      "type": "stdio"
    }
  }
}

With logging enabled for troubleshooting:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "@microsoft/dataverse",
        "mcp",
        "https://yourorg.crm.dynamics.com",
        "--log-level", "Debug",
        "--log-file"
      ],
      "type": "stdio"
    }
  }
}

Using the preview endpoint:

{
  "mcpServers": {
    "dataverse": {
      "command": "npx",
      "args": [
        "-y",
        "@microsoft/dataverse",
        "mcp",
        "https://yourorg.crm.dynamics.com",
        "--preview"
      ],
      "type": "stdio"
    }
  }
}

Authentication

The CLI uses Microsoft Authentication Library (MSAL) for authentication. Profiles and tokens are cached locally.

First-time setup:

dataverse auth create --environment https://myorg.crm.dynamics.com

This opens a browser or system authentication dialog. After signing in, the profile is saved and subsequent commands (including mcp) use cached tokens without re-prompting.

Multiple environments:

dataverse auth create --environment https://dev.crm.dynamics.com --name dev
dataverse auth create --environment https://prod.crm.dynamics.com --name prod
dataverse auth select --name dev

Service principal (CI/CD):

dataverse auth create --applicationId <appId> --clientSecret <secret> --tenant <tenantId> --environment https://myorg.crm.dynamics.com

Supported Platforms

• Windows (x64, ARM64)
• macOS (x64, ARM64 / Apple Silicon)
• Linux (x64, ARM64)

Troubleshooting

Enable Logging

If you encounter issues, enable file logging to capture detailed diagnostic information:

dataverse mcp https://yourorg.crm.dynamics.com --log-level Debug --log-file

Log files are written to your system's temporary directory. The exact location will be displayed when logging starts.

Common Issues

"No compatible binary found for your platform"

• Supported: Windows (x64, ARM64), macOS (x64, ARM64), Linux (x64, ARM64)
• For other platforms, please build from source with dotnet publish

Authentication failures

• Ensure you have access to the Dataverse environment
• Check that your organization URL is correct
• Try clearing your token cache and re-authenticating

MCP connection issues in Claude Desktop

• Verify the configuration JSON syntax is correct
• Check that the organization URL is accessible
• Enable --log-file to capture detailed error messages
• Restart Claude Desktop after configuration changes

Getting Help

dataverse --help
dataverse auth --help
dataverse auth create --help
dataverse org --help
dataverse mcp --help
dataverse mcp allow --help
dataverse erp batch --help

Supported MCP Operations

The MCP server supports the following operations:

• Tools: List and call Dataverse tools
• Prompts: List and retrieve prompts
• Resources: List and read Dataverse resources

License

MIT

Links

• GitHub Repository
• Model Context Protocol
• Claude Desktop