MCP Dataverse Server

MCP server that exposes the Microsoft Dataverse Web API as 50 AI-callable tools — enabling GitHub Copilot, Claude, and other MCP clients to query, create, and manage Dataverse records without hallucinating schema.

Install

✅ Recommended — Interactive CLI (VS Code 1.99+)

npx mcp-dataverse install

The wizard will:

1. Ask for your Dataverse environment URL
2. Save configuration to ~/.mcp-dataverse/config.json
3. Register the server in VS Code and/or VS Code Insiders via code --add-mcp
4. Authenticate with your Microsoft account (device code flow)

After the wizard completes, the server is immediately available in VS Code — open Copilot chat and the 50 Dataverse tools are ready.

Requires VS Code 1.99+ — the CLI registration uses code --add-mcp, introduced in March 2025. If neither code nor code-insiders is on your PATH, the wizard prints a manual snippet to copy-paste. Custom VS Code profiles are also detected and patched automatically.

---

Alternative — VS Code Command Palette

1. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
2. Type MCP: Add Server → choose NPM Package → enter mcp-dataverse
3. Choose the scope: User or Workspace
4. Edit the generated entry to add your environment URL:

{
  "servers": {
    "mcp-dataverse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-dataverse"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/.mcp-dataverse/config.json"
      }
    }
  }
}

---

Manual (mcp.json)

Create or edit .vscode/mcp.json (workspace scope) or the user-level mcp.json (Ctrl+Shift+P → MCP: Open User Configuration):

{
  "servers": {
    "mcp-dataverse": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-dataverse"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/.mcp-dataverse/config.json"
      }
    }
  }
}

---

Authentication — automatic, no setup required

No PAC CLI, no Azure AD app registration, no credentials to configure.

The server uses Microsoft's device code flow (MSAL Public Client) — the same mechanism used by Power Platform CLI. Zero pre-configuration: just set your environment URL and the server handles the rest.

First connection — what you'll see

Authentication is triggered on the first tool call after the server starts (e.g. asking Copilot "Who am I in Dataverse?"). Here is the exact sequence:

Step 1 — Open the Output panel

In VS Code: View → Output → select MCP in the dropdown.

Step 2 — The sign-in prompt appears

[mcp-dataverse] First-time authentication required.
Environment: https://yourorg.crm.dynamics.com
Open the URL below in your browser to sign in.

[mcp-dataverse] Sign in required

  1. Open https://microsoft.com/devicelogin in your browser
     (use the browser profile linked to your Power Platform account)
  2. Paste the code: ABCD-1234  (already copied to your clipboard)
  3. Sign in with your work account

Step 3 — Sign in

1. Open https://microsoft.com/devicelogin in the browser/profile linked to your Power Platform work account
2. Paste the code — it's already in your clipboard
3. Complete Microsoft sign-in with your work account

Step 4 — Confirmation in the Output panel

[mcp-dataverse] Authenticated ✓  Token cached — no sign-in needed next time.

The tool call that triggered auth now completes. All 50 tools are ready to use.

⏱ The code expires after 5 minutes. If it times out, retry the tool call — a new code will be generated.

Why not auto-open the browser? Consultants often work with multiple browser profiles (personal vs. work). Device code flow intentionally lets you choose the right browser and profile.

Subsequent launches

The token is cached encrypted (AES-256-GCM) in ~/.mcp-dataverse/. On all future server starts, renewal is completely silent — no prompt, no browser.

You only need to re-authenticate if the refresh token expires (~90 days of inactivity) or you reset it manually:

npx mcp-dataverse-auth https://yourorg.crm.dynamics.com

When re-auth is needed, the Output panel shows:

[mcp-dataverse] Session expired — re-authenticating.
Open the URL below in your browser to sign in again.

[mcp-dataverse] Sign in required
  ...

The same device code process applies.

---

Prerequisites

• Node.js 20+
• VS Code + GitHub Copilot (Agent mode)
• A Dataverse environment with a licensed user account

Quick Start (< 5 min)

1. Clone & install

git clone <repo-url> mcp-dataverse && cd mcp-dataverse
npm install

2. Configure

cp config.example.json config.json

Edit config.json:

| Field | Description | | ------------------ | ----------------------------------------------------- | | environmentUrl | Your org URL, e.g. https://yourorg.crm.dynamics.com | | requestTimeoutMs | HTTP timeout in ms (default: 30000) | | maxRetries | Retry count on transient errors (default: 3) |

3. Authenticate

npm run auth:setup

Runs device code authentication. Follow the URL printed to the terminal — sign in with your Power Platform account. Token is cached and silently renewed.

4. Build

npm run build

5. Verify the connection

npx tsx tests/live/test-whoami.ts

Expected output:

WhoAmI result: { UserId: 'xxxxxxxx-...', BusinessUnitId: 'xxxxxxxx-...', OrganizationId: 'xxxxxxxx-...' }

6. Configure VS Code

.vscode/mcp.json is already present in this repo. If you need to add it manually:

{
  "servers": {
    "dataverse": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/server.js"],
      "env": {}
    }
  }
}

1. Restart VS Code
2. Open GitHub Copilot chat → switch to Agent mode (⚡)
3. Test: "List the Dataverse tables in my environment"

---

Tools (50)

| Tool | Category | Description | | -------------------------------------------- | ------------- | ----------------------------------------------------------------------------------- | | dataverse_whoami | Auth | Verify connection; returns UserId, BusinessUnitId, OrgId | | dataverse_list_tables | Metadata | List all tables (customOnly filter available) | | dataverse_get_table_metadata | Metadata | Full schema: columns, types, logical names | | dataverse_get_relationships | Metadata | All 1:N, N:1, N:N relationships for a table; filter by relationshipType | | dataverse_list_global_option_sets | Metadata | All global option sets in the environment | | dataverse_get_option_set | Metadata | Options and values for a specific option set | | dataverse_get_entity_key | Metadata | Alternate key definitions for a table (fields, index status, customizable flag) | | dataverse_query | Query | OData query with $select, $filter, $orderby, $expand, $count | | dataverse_execute_fetchxml | Query | Raw FetchXML for aggregations and complex joins | | dataverse_retrieve_multiple_with_paging | Query | Paginated query following @odata.nextLink, with configurable maxTotal cap | | dataverse_get | CRUD | Retrieve a single record by GUID | | dataverse_create | CRUD | Create a record; returns the new GUID | | dataverse_update | CRUD | Patch a record — only specified fields are changed | | dataverse_delete | CRUD | Delete a record (requires explicit confirm) | | dataverse_upsert | CRUD | Create-or-update via alternate key | | dataverse_assign | CRUD | Assign a record to a different user or team owner | | dataverse_associate | Relations | Associate two records via a named relationship | | dataverse_disassociate | Relations | Remove an association between two records | | dataverse_execute_action | Actions | Execute a global (unbound) Dataverse action | | dataverse_execute_function | Actions | Execute a global read-only function (e.g. WhoAmI) | | dataverse_execute_bound_action | Actions | Execute an action bound to a specific record | | dataverse_execute_bound_function | Actions | Execute an OData bound function on a specific record | | dataverse_retrieve_dependencies_for_delete | Actions | Check what components block deletion of a Dataverse component | | dataverse_list_dependencies | Actions | List component dependencies before modifying or deleting | | dataverse_batch_execute | Batch | Up to 1000 operations in a single HTTP batch request; optional atomic changeset | | dataverse_change_detection | Tracking | Delta tracking using change tokens to detect record changes since last sync | | dataverse_solution_components | Solution | List all components in a named solution; filter by component type code | | dataverse_publish_customizations | Solution | Publish pending customizations (all or targeted entities/web resources/option sets) | | dataverse_impersonate | Impersonation | Execute any tool on behalf of another Dataverse user via MSCRMCallerId | | dataverse_list_custom_actions | Customization | Lists custom actions (custom API / SDK messages) in the environment | | dataverse_list_plugin_steps | Customization | Lists plugin step registrations with stage, mode, entity, and state | | dataverse_get_environment_variable | Environment | Retrieve an environment variable definition and current value | | dataverse_set_environment_variable | Environment | Set or update an environment variable value | | dataverse_get_plugin_trace_logs | Trace | Retrieve plugin execution trace logs for debugging | | dataverse_get_workflow_trace_logs | Trace | Retrieve async workflow/system job execution logs | | dataverse_search | Search | Full-text Relevance Search across all configured tables | | dataverse_get_audit_log | Audit | Retrieve audit trail for a record showing change history | | dataverse_detect_duplicates | Quality | Check for potential duplicates before creating a record | | dataverse_get_annotations | Annotations | Retrieve notes and file attachments linked to a record | | dataverse_list_users | Users | Search system users by name or email with BU filtering | | dataverse_get_user_roles | Users | Security roles assigned to a system user | | dataverse_create_annotation | Annotations | Create a note or file attachment linked to a record | | dataverse_get_attribute_option_set | Metadata | Local/entity-specific option set values (statecode, statuscode, picklist) | | dataverse_list_solutions | Solution | List all solutions in the environment | | dataverse_set_workflow_state | Customization | Enable or disable a workflow or process | | dataverse_list_views | Views | List system and personal saved views for a table | | dataverse_upload_file_column | Files | Upload binary content to a file/image column on a record | | dataverse_download_file_column | Files | Download binary content from a file/image column on a record | | dataverse_list_business_units | Org | List business units in the environment (org hierarchy) | | dataverse_list_teams | Teams | List Dataverse teams with optional filter by team type |

---

Scripts

| Command | Description | | -------------------------- | ----------------------------------- | | npm run build | Compile TypeScript → dist/ | | npm run dev | Watch mode — no build step needed | | npm start | Start the compiled server | | npm run auth:setup | One-time device code authentication | | npm run typecheck | Type-check without emitting output | | npm run lint | ESLint on src/ | | npm run test:unit | Unit tests only | | npm run test:integration | Integration tests | | npm test | All tests |

---

Architecture

TypeScript MCP server over stdio transport. The DeviceCodeAuthProvider (MSAL device code flow) injects Bearer tokens into a native-fetch-based HttpClient wrapped by DataverseClient. Each tool module registers handlers with the MCP Server instance.

GitHub Copilot → stdio → MCP Server → Tool Router → DataverseClient → Dataverse Web API v9.2
                                                           └── DeviceCodeAuthProvider (MSAL)

---

Security

• Never commit config.json — it is in .gitignore
• Token cache (~/.mcp-dataverse/) is encrypted (AES-256-GCM) and should not be shared
• Tokens are never logged; only diagnostic messages are written to stderr
• Tokens are scoped to the authenticated user — no privilege escalation

---

Troubleshooting

| Symptom | Fix | | ------------------------------------------ | -------------------------------------------------------------------------------- | | No sign-in prompt appeared | Open View → Output → MCP in VS Code — the device code is displayed there | | Browser didn't open automatically | Copy the URL from the Output panel manually: https://microsoft.com/devicelogin | | No MSAL accounts found | Run npx mcp-dataverse-auth to re-authenticate, then restart the server | | Authentication timed out | The 5-minute window expired — restart the MCP server to get a new code | | "https://" is required | Check your ~/.mcp-dataverse/config.json — URL must start with https:// | | Server not appearing in Copilot Agent mode | Re-run npx mcp-dataverse install; check Output → MCP panel for errors | | Install wizard says "not found on PATH" | Install VS Code Shell Command (Ctrl+Shift+P → Shell Command: Install...) or use the manual snippet provided |