Dataverse

Microsoft Dataverse

Entry point for working with Microsoft Dataverse (Power Platform / Dynamics 365) from a coding agent. It installs the specialist Dataverse skills, connects the environment, and routes each request to the right skill.

How to use this skill (read first -- act, do not stall)

When the user asks to connect / set up / authenticate / switch an environment, or to read / query / write Dataverse data:

1. Act now, in this turn. Work through the steps below immediately. Do not stop or report a blocker because the specialist skills, the Dataverse CLI, Python, or MCP tools are missing -- installing and authenticating them IS the task, not a reason to stop.
2. Do not re-ask for what you were given. If the request already contains the environment URL, use it.
3. A Dataverse CLI profile is enough to authenticate AND answer data queries. The MCP server and Python SDK are optional -- never require them for a connect or a simple read.
4. If a cached or stale skill path fails to resolve, find the active dataverse skill and continue from it.

Step 1: Install the specialist skills (run now)

If dv-overview / dv-connect / the needed dv-* skill is not already installed, run this immediately -- do not ask first, and do not report the missing skill as a blocker:

Copy code
npx skills add microsoft/Dataverse-skills -s "*" -g

The -g flag installs the skills globally for every agent and project (under your global skills dir, e.g. ~/.agents/skills and ~/.codex/skills), so they persist across sessions and projects. Read dv-overview and dv-connect in the same turn and continue. If network policy blocks the command, request network escalation and retry before reporting it blocked.

Step 2: Install the Dataverse CLI

Python is optional. It is needed only for the Python SDK paths (dv-data / dv-query bulk + analytics) and scripts/auth.py. If Python is absent, continue with the CLI, note that the SDK path was skipped, and do not install an interpreter unless the task needs it.

Step 3: Authenticate (CLI)

Copy code
dataverse auth create --environment <your-environment-url>

If interactive auth produces no prompt (a restricted or headless host), stop it and retry with --deviceCode, then share the device code with the user. Record DATAVERSE_URL and TENANT_ID in a project .env. If an admin-consent error appears, share the exact consent URL the CLI prints -- never synthesize one.

Step 4: Verify, then serve the request

Copy code
dataverse auth who       # confirms the profile + environment
dataverse org who        # confirms the data plane

Once the profile targets the right environment, you are connected for CLI data work -- route to the specialist skill and answer the request now. Example read:

Copy code
dataverse data query --sql "SELECT TOP 10 firstname, lastname FROM contact WHERE lastname LIKE 'A%' ORDER BY lastname, firstname" --json

When the user says "top N" without giving a ranking, pick a sensible sort (e.g. alphabetical) and state which you used.

Step 5 (optional): MCP server + Python SDK

Do this only when the user wants in-agent Dataverse tools (MCP) or bulk / analytics via the Python SDK. Neither is required for CLI reads.

• MCP: set MCP_CLIENT_ID in .env (Copilot aebc6443-996d-45c2-90f0-388ff96faa56; Claude / Cursor / Codex 0c412cc3-0dd6-449b-987f-05b053db9457), register npx @microsoft/dataverse mcp <url> in the agent's MCP config (.mcp.json for Copilot, claude mcp add for Claude, ~/.cursor/mcp.json for Cursor, ~/.codex/config.toml for Codex), then allowlist with dataverse mcp allow <MCP_CLIENT_ID> (or python scripts/enable-mcp-client.py if dv-connect fetched it). The agent must restart before MCP tools load. Tenant admin consent gates MCP registration only -- CLI reads may proceed from the authenticated profile while consent is pending.
• Python SDK: pip install --upgrade PowerPlatform-Dataverse-Client python-dotenv azure-identity msal msal-extensions requests pandas.

Connection states (report precisely -- do not conflate)

• CLI authenticated -- dataverse auth who shows the intended URL + user.
• Data-plane reachable -- a real read succeeds (e.g. a small dataverse data query).
• MCP configured -- client allowlisted, GA validation passes, host config points at the URL (a Preview 403 is expected when GA is valid).
• MCP loaded -- the agent was restarted and now exposes the Dataverse tools.

Never claim MCP is connected just because CLI auth succeeded.

Telemetry attribution (JetBrains)

When dv-connect runs under a JetBrains IDE it detects the surface and appends a /jetbrains suffix to the agent, writing DATAVERSE_PLUGIN_AGENT=<agent>/jetbrains (e.g. codex/jetbrains) to .env; scripts/auth.py then stamps agent=<agent>/jetbrains into the operation-context so Dataverse telemetry attributes the traffic to JetBrains. If the suffix is missing after connect, append /jetbrains to the DATAVERSE_PLUGIN_AGENT value yourself. Use the verified plugin version in any attribution context (read it from the plugin manifest) -- never guess it.

Helper scripts

scripts/auth.py (auth + attribution) and scripts/enable-mcp-client.py (MCP allowlist) are not bundled with this tile -- the dv-connect skill fetches them from canonical (microsoft/Dataverse-skills) into the project scripts/ directory at connect-time. Only the Python SDK path and the script-based MCP allowlist need them; CLI reads do not. If a task needs scripts/auth.py and it is absent, run dv-connect first. Do not imply auth.py ran if Python is absent.