dv-connect

Skill: Connect

One-step, idempotent Dataverse connection. Each step checks if it's already done and skips.

Environment-First Rule — All metadata and plugin registrations are created in the environment via API/scripts, then pulled into the repo. Never hand-write solution XML to create components.

Execute steps in order; do not skip ahead. Exception: Step 0 can short-circuit the flow if the workspace is already set up.

Host entry test (FIRST — before Step 0). A local Windows/macOS host is capable by default, whichever agent drives it — it can run the CLIs, use persistent credentials, and host local MCP servers; an approval/sandbox gate isn't a constraint, and a missing CLI = install it. Constrained only when a runtime can't start, auth can't persist, or the host is explicitly ChatGPT Work Mode / Codex cloud / CI / no-keyring Linux (deterministic table: headless-hosts.md). Constrained → install only Python + pip deps, .env, scripts/auth.py, verify python scripts/auth.py --check, skip CLI / PAC / MCP. Capable → normal flow below.

Step 0: Detect existing setup (run this first)

Before touching anything, check whether this workspace is already connected to a Dataverse environment. Repeating setup on an already-configured workspace overwrites .env, re-registers MCP, and wastes time.

Gemini supports GA only. If Preview is requested, explain and stop before setup shortcuts.

Run these checks in order. If all four pass, skip straight to Step 7 (final verification) and stop there.

1. .env is present and complete — file exists at the workspace root and contains non-empty values for DATAVERSE_URL, TENANT_ID, and MCP_CLIENT_ID
2. MCP is registered — the host MCP list has a dataverse-* entry, or Gemini has its bundled dataverse entry, pointing at DATAVERSE_URL
3. Both auth surfaces match .env — dataverse auth who shows a profile whose Environment Url matches DATAVERSE_URL, AND pac org who against a PAC profile for the same URL succeeds. (DV CLI auth covers Connect / Data / Query / Metadata / MCP / Python; PAC auth covers dv-solution and dv-admin. Both are front-loaded at connect time so neither prompts later.)
4. Python SDK is importable and current — python -c "from PowerPlatform.Dataverse.client import DataverseClient; import pandas; from importlib.metadata import version; v=version('PowerPlatform-Dataverse-Client'); parts=tuple(int(p) for p in v.split('.')[:2]); assert parts>=(1,1), f'SDK {v} is outdated, need >=1.1.0'" exits 0

If all pass: First ensure .env has valid attribution — set DATAVERSE_PLUGIN_VERSION to the loaded manifest version and add DATAVERSE_PLUGIN_AGENT (detected host, per Step 3) if absent or a stale unknown/placeholder. Confirm the detected setup (URL, profile, MCP server), and jump to Step 7. Do not otherwise rewrite .env, re-register MCP, or re-run pip install.

If any check fails: Proceed through the normal flow (Steps 1–7), but still use each step's own skip condition. A partially-configured workspace doesn't need a full redo — e.g., if only .env and MCP are missing but tools and auth are fine, start at Step 2 or Step 3.

Step 1: Ensure tools are installed

Check each tool independently -- report all missing tools at once. See tools-setup.md for install commands.

.NET SDK is needed for PAC CLI but NOT for the Dataverse CLI (the npm package bundles its own runtime). Node.js powers the Dataverse CLI npm package (@microsoft/dataverse), which is used as the MCP proxy and for scripted data plane actions. Azure CLI is used as a fallback for environment discovery when PAC CLI isn't available (see mcp-configuration.md Step 3b). GitHub CLI is not needed for connecting — it's used later for ALM/CI/CD scenarios (see dv-solution).

If any tool is missing, install it (see tools-setup.md), then verify. If winget installs a tool but it's not in PATH, ask the user to restart the terminal.

After Python is confirmed, check if deps are already present before installing:

python -c "from PowerPlatform.Dataverse.client import DataverseClient; import azure.identity, msal, msal_extensions, requests, pandas; print('OK')"

If it prints OK, skip pip. Otherwise:

pip install --upgrade azure-identity requests PowerPlatform-Dataverse-Client pandas msal msal-extensions

msal + msal-extensions let scripts/auth.py reuse the dataverse auth create cache -- one sign-in for CLI, MCP, Python.

After Node.js is confirmed, install the Dataverse CLI only if missing (do not re-run on every connect -- on managed devices each @latest fetch can trigger npm-registry security prompts; see tools-setup.md):

npm install -g @microsoft/dataverse@latest

Skip condition: All tools present, Python SDK installed, and pandas importable (python -c "import pandas").

Step 2: Discover and select the environment

Before asking the user for a URL, check what's already available.

Auth tool choice. Two tools, two AAD apps, two caches — front-load both at connect:

1. dataverse auth create (app 0c412cc3-…) covers DV CLI + MCP + Python.
2. pac auth create (PAC's own app) covers dv-solution + dv-admin.

Check for an existing DV CLI profile first, then fall back to PAC for environment discovery if needed:

dataverse auth list
dataverse auth who
pac auth list   # PAC profiles are still useful for env discovery / pac org list

If dataverse auth who shows a profile and its environment matches the user's target:

• Reuse it. Set DATAVERSE_URL and TENANT_ID from the profile.

If no DV CLI profile exists (or it points at the wrong environment):

• Ask: "Do you want to connect to an existing environment or create a new one?"

Before selecting, check for tenant/region mismatch. If the target URL uses a different region than the authenticated account's environments, create a new profile for the correct tenant rather than reuse the old one:

dataverse auth create --environment <url>          # interactive (WAM broker on Windows → no browser tab)
dataverse auth create --environment <url> --deviceCode   # headless / remote / SSH

If the user hits an admin-consent error, the CLI prints the correct scope-scoped consent URL to share with a tenant admin — do not synthesize one.

To switch between existing DV CLI profiles:

dataverse auth select --name <profile-name>

To create a new environment (requires admin permissions):

pac admin create --name "<name>" --type "<type>" --region "<region>"

If this fails with permissions error, guide the user to Power Platform Admin Center to create it, then connect.

Confirm connection:

dataverse auth who
dataverse org who --context "app=dataverse-skills/<ver>;skill=dv-connect;agent=<agent>"

Parse the output to extract DATAVERSE_URL, TENANT_ID, and — on ERP-linked envs — ERP_URL (see erp-detection.md).

If neither command shows a tenant ID, fall back to:

curl -sI https://<org>.crm.dynamics.com/api/data/v9.2/ \
  | grep -i "WWW-Authenticate" \
  | sed -n 's|.*login\.microsoftonline\.com/\([^/]*\).*|\1|p'

Step 2b: Front-load PAC CLI auth for the same environment

PAC uses its own AAD app, so a separate sign-in is required for dv-solution and dv-admin — do it now.

pac auth list                                       # skip if a profile for $DATAVERSE_URL exists
pac auth create --name <orgid> --environment <DATAVERSE_URL>

Use the same account as Step 2. If PAC CLI is not installed, skip with a note that dv-solution / dv-admin will need it later.

Step 3: Create .env

Present authentication options:

How would you like to authenticate with Dataverse?

1. Interactive login (recommended) — Sign in via browser. No app registration needed. Token stays cached across sessions.
2. CI/CD service principal — Use CLIENT_SECRET or CLIENT_CERTIFICATE_PATH.

Write .env directly — do not instruct the user to create it:

Use one detected tool_type to derive both MCP_CLIENT_ID and canonical attribution. Set PLUGIN_VERSION from the loaded manifest; Antigravity uses .claude-plugin/plugin.json because native plugin.json has none.

tool_type = "<copilot | claude | cursor | codex | gemini | antigravity | unknown>"
plugin_version = "<plugin manifest version, e.g. 1.5.0>"
mcp_client_id = "aebc6443-996d-45c2-90f0-388ff96faa56" if tool_type == "copilot" else "0c412cc3-0dd6-449b-987f-05b053db9457"
agent_host = {
    "copilot": "copilot", "claude": "claude-code", "cursor": "cursor",
    "codex": "codex", "gemini": "gemini-cli",
    "antigravity": "antigravity-cli",
}.get(tool_type, "unknown")
ide = "<jetbrains if a JetBrains install, else empty; see references/helper-scripts.md>"
agent_host += f"/{ide}" if ide else ""

with open(".env", "w") as f:
    f.write(f"DATAVERSE_URL={dataverse_url}\n")
    f.write(f"TENANT_ID={tenant_id}\n")
    f.write(f"MCP_CLIENT_ID={mcp_client_id}\n")
    f.write(f"DATAVERSE_PLUGIN_VERSION={plugin_version}\n")
    f.write(f"DATAVERSE_PLUGIN_AGENT={agent_host}\n")
    f.write(f"SOLUTION_NAME={solution_name}\n")
    f.write(f"PUBLISHER_PREFIX=\n")  # filled in when solution is created
    f.write(f"PAC_AUTH_PROFILE=nonprod\n")
    if client_id:
        f.write(f"CLIENT_ID={client_id}\n")
    if client_secret:
        f.write(f"CLIENT_SECRET={client_secret}\n")

Ensure .env is in .gitignore:

import os

GITIGNORE_ENTRIES = [
    ".env", ".vscode/settings.json", ".claude/mcp_settings.json",
    ".token_cache.bin", ".dataverse/", "*.snk", "__pycache__/", "*.pyc",
    "solutions/*.zip", "plugins/**/bin/", "plugins/**/obj/",
]
gitignore = open(".gitignore").read() if os.path.exists(".gitignore") else ""
missing = [e for e in GITIGNORE_ENTRIES if e not in gitignore]
if missing:
    with open(".gitignore", "a") as f:
        f.write("\n" + "\n".join(missing) + "\n")

Skip condition: .env already exists with all required values.

Step 4: Set up project structure (new projects only)

If this is a new project (no scripts/ directory):

mkdir -p solutions plugins scripts

Ensure scripts/auth.py and scripts/enable-mcp-client.py exist -- see references/helper-scripts.md.

Copy templates/CLAUDE.md to the repo root if it doesn't exist. Replace placeholders ({{DATAVERSE_URL}}, {{SOLUTION_NAME}}, {{PUBLISHER_PREFIX}}) with values from .env.

Step 5: Verify the connection

dataverse auth who
pac org who
python scripts/auth.py --check

--check makes a real data-plane call (not just a token) — the only proof the org is actually reachable; a token can be minted while the org domain is blocked. All must resolve the same user/environment, proving the DV CLI cache, the PAC profile (Step 2b), and Python's reuse of the shared cache are wired.

If any fail:

• dataverse auth who fails → re-run Step 2.
• pac org who fails → re-run Step 2b.
• python scripts/auth.py --check prints a device-code URL → browser/WAM cache has no Python-reusable token. Auto-fix: re-run dataverse auth create --environment <url> --deviceCode, then retry. If it still prompts, check pip show msal msal-extensions. Headless hosts (ChatGPT / Codex cloud / CI): dataverse auth create can't persist here — don't loop (see headless-hosts.md).
• python scripts/auth.py --check prints NOT REACHABLE with a connection/timeout error → the org domain is blocked by network egress, not auth. Do NOT report success or a count — see headless-hosts.md remediation.
• Other Python error → check SDK install and .env.

Before metadata work, also confirm the account has the prvCreateEntity customization privilege — see tools-setup.md.

Step 6: Configure MCP server

Skip this step only when the current host points to the selected environment:

• Gemini: gemini mcp list resolves bundled server dataverse to the selected URL
• Antigravity: agy mcp list contains the selected environment
• Other hosts: their MCP list or config contains a Dataverse server for the selected URL

If MCP is not configured, follow mcp-configuration.md:

1. Detect which tool the user is running (Copilot, Claude, Cursor, Codex, Gemini, or Antigravity) from context
2. Set MCP_CLIENT_ID based on tool choice
3. Get environment URL from .env
4. Default to GA endpoint (/api/mcp)
5. Register the MCP server per host (see the per-host blocks below)
6. Handle Dataverse admin consent and allowlist — prefer dataverse mcp allow <MCP_CLIENT_ID> over the portal (one-time per tenant/environment)
7. If ERP_URL exists, separately allowlist and validate ERP

Plugin attribution for MCP: This plugin uses the stdio proxy transport (npx @microsoft/dataverse mcp <url>). When registering it, include DATAVERSE_OPERATION_CONTEXT in the env block so the CLI appends it to its User-Agent on requests to /api/mcp. Build the value from .env:

DATAVERSE_OPERATION_CONTEXT=app=dataverse-skills/{DATAVERSE_PLUGIN_VERSION};skill=mcp-direct;agent={DATAVERSE_PLUGIN_AGENT}

For Claude Code (claude mcp add -t stdio), pass it via -e DATAVERSE_OPERATION_CONTEXT=.... For JSON/TOML hosts, add it to the server's environment block.

Important: MCP configuration requires an editor/CLI restart.

For Copilot: Write the JSON config, then:

✅ Dataverse MCP server configured. Restart your editor for changes to take effect.

For Claude: Run the claude mcp add command, then warn the user about the auth popup that will appear on next launch:

✅ Dataverse MCP server registered. Restart Claude Code to enable MCP tools. Remember to use claude --continue to resume the session without losing context.

On restart, a browser window may open to sign in to your Dataverse environment (the MCP proxy authenticating on your behalf). See mcp-configuration.md for details.

For Cursor: Write the JSON config, then:

✅ Dataverse MCP server dataverse-{orgid} configured in ~/.cursor/mcp.json. Reload the Cursor window (Ctrl+Shift+P → "Developer: Reload Window") for the new MCP server to appear under Settings → Tools & MCPs.

On first use the npx @microsoft/dataverse proxy signs in via browser device code, then reuses the shared cache silently. See mcp-configuration.md.

For Codex: Write the TOML config to ~/.codex/config.toml. Codex loads MCP tools only at startup, so don't claim they're callable until the user restarts. Tell the user:

✅ Dataverse MCP server dataverse-{orgid} configured in ~/.codex/config.toml. Restart Codex (CLI) or reload the Codex IDE to load the MCP tools.

Step 7: Final verification

After the editor/CLI restarts, both of these must succeed before declaring the setup complete:

Check 1: the host's MCP list shows the Dataverse server connected

• Claude: claude mcp list
• Gemini: gemini extensions list, then gemini mcp list
• Antigravity: agy mcp list; after restart, /mcp This proves the MCP server starts, but not that data operations work.

Check 2: Agent successfully lists tables via describe/search and returns data

"List the tables in my Dataverse environment."

This proves end-to-end wiring: auth, tenant consent, environment allowlist, and endpoint reachability are all correct. If the agent falls back to PAC CLI or Web API, see mcp-configuration.md troubleshooting.

Only when both checks pass is the setup verified.

Interpreting failures:

• If Check 1 fails (server not ✓ Connected): the MCP server itself cannot start. Re-run Step 6 and check that npx/Node.js are installed and the MCP registration succeeded.
• If Check 1 passes but Check 2 fails (server starts but describe/search errors): the server can speak MCP but cannot reach or read Dataverse. Run --validate below to diagnose.

Diagnostic — --validate (for failure investigation only):

npx @microsoft/dataverse mcp {DATAVERSE_URL} --validate

This exercises two Dataverse MCP endpoints with a fresh authentication handshake and reports detailed errors (auth, allowlist, consent, endpoint reachability):

• GA / Production endpoint — {DATAVERSE_URL}/api/mcp. This is the one the plugin actually uses at runtime.
• Preview endpoint — {DATAVERSE_URL}/api/mcp_preview. Opt-in per environment; not used by the plugin.

Do not use --validate as a success gate on first-time setup. On a freshly configured workspace, the token cache hasn't warmed up, so --validate can fail with MsalClientException or 403 while MCP is actually working fine on subsequent real calls. Reserve --validate for diagnosing a confirmed failure in Check 1 or Check 2.

How to read --validate output:

• Look at the GA / Production endpoint (/api/mcp) result first. If this passes, MCP will work for normal plugin usage regardless of what the Preview endpoint reports.
• A 403 Forbidden on the Preview endpoint (/api/mcp_preview) is expected for most environments. Preview is opt-in per environment; if your environment hasn't enabled it, the Preview check will always fail. This does not indicate a broken setup.
• Ignore the overall exit code and the ⚠ Partial success warning in this case. The validator returns exit code 1 (failure) unless BOTH /api/mcp and /api/mcp_preview pass. Because most environments don't enable the Preview endpoint, --validate will exit 1 even when MCP is fully functional via the GA endpoint. Focus on per-endpoint results, not the aggregate status.
• If the GA endpoint (/api/mcp) fails: that's the real signal to investigate — auth, tenant consent, environment allowlist, or endpoint reachability.

MCP Server Capabilities

For what MCP can and can't do (data CRUD + batch up to 25, table/column creation incl. choice/lookup, search/describe, file upload/download) versus the SDK / Web API, see the overview skill's Tool Capabilities matrix.

After verifying MCP works, tell the user:

✅ Connected to Dataverse at {DATAVERSE_URL}. Tools installed, authenticated, MCP live.

You can now:

• Create tables, columns, and relationships (dv-metadata)
• Write and import data (dv-data)
• Query and analyze data (dv-query)
• Export and promote solutions (dv-solution)

To create your first solution, see the dv-solution skill. To load sample data (accounts, contacts, opportunities), ask: "Load demo data into my Dataverse environment."

Supported Agents

This plugin's skills are natively loaded by GitHub Copilot CLI, Claude Code CLI, Gemini CLI, and Antigravity CLI when installed as a plugin. No manual context loading is needed.

The PAC CLI commands, Python scripts, and XML templates work identically across hosts.