Dataverse MCP Server

An MCP server that connects Claude to Microsoft Dataverse via the Dataverse Web API v9.2. Designed for everyday users who work with Dataverse records — not for admin operations like managing environments, solutions, or security roles. Authenticates via interactive browser sign-in (no client secrets required) with persistent token and schema caching.

---

Available Tools

Tool	Cached	Description
Sign in to Dataverse	—	Start interactive browser sign-in; returns a URL, token exchange happens automatically on redirect
Sign out from Dataverse	—	Sign out and clear cached identity; use to switch accounts
Get my identity	24 hour TTL	Get the current user's GUID, display name, business unit, org ID, and timezone
List tables	24 hour TTL	List all tables with LogicalName, DisplayName, and EntitySetName
Get table schema	1 hour TTL	Retrieve field definitions, types, and required fields per table
Refresh schema cache	—	Force a fresh schema fetch; use if schema seems stale after customizations
List records	—	Query records with OData $filter, $select, $orderby, and pagination
Create record	—	Create a new record (always call Get table schema first)
Update record	—	Partially update an existing record via PATCH
Delete record	—	Permanently delete a record

---

Prerequisites

• Docker and Docker Compose installed
• A Microsoft Dataverse / Power Platform environment URL
• A Microsoft account with access to that environment

---

Setup

1. Clone and configure

git clone <repo-url>
cd dataverse-mcp
cp .env.example .env

Edit .env and set at minimum:

DATAVERSE_URL=https://yourorg.crm4.dynamics.com
CLIENT_ID=your-client-id-here

CLIENT_ID is required — register an app in Azure Portal (see Registering Your Own Azure AD App).

2. Build the Docker image

docker compose build

---

Connecting to Claude Desktop

Claude Desktop launches the MCP server as a subprocess via stdio each time it starts.

Configure Claude Desktop

Find your config file:

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

Add the following, replacing the path with the absolute path to your cloned repo:

{
  "mcpServers": {
    "Dataverse": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/absolute/path/to/dataverse-mcp/docker-compose.yml",
        "run", "--rm", "-i", "--service-ports",
        "dataverse-mcp"
      ]
    }
  }
}

Windows path example:

"args": [
  "compose",
  "-f", "C:/Users/yourname/dataverse-mcp/docker-compose.yml",
  "run", "--rm", "-i", "--service-ports",
  "dataverse-mcp"
]

Restart Claude Desktop

Fully quit and reopen Claude Desktop. The Dataverse server will appear in the tools list (hammer icon).

First sign-in (Claude Desktop)

Start a conversation and ask Claude to do something with Dataverse, e.g.:

"Show me my recent contacts in Dataverse"

Claude will call a Dataverse tool, get an authentication error, and automatically call Sign in to Dataverse. A sign-in URL will appear — open it in your browser and sign in with your Microsoft account. Your browser will show "Authentication complete" when done. Tell Claude you've signed in and it will proceed with your request.

You will not need to sign in again until the refresh token expires (Microsoft default: 90 days of inactivity).

---

Connecting to Claude Code

Claude Code uses a persistent MCP server process rather than spawning a new one per session. The server runs as a long-lived daemon and Claude Code connects to it over HTTP/SSE.

Step 1 — Start the server in SSE mode

The default transport is stdio (for Claude Desktop). For Claude Code you need the server running and listening on a port. The repo includes docker-compose.sse.yml which overrides the transport to SSE and publishes port 8199. Start it with:

docker compose -f docker-compose.yml -f docker-compose.sse.yml up -d

Verify it is running:

curl http://localhost:8199/sse
# Should return an SSE stream (hang open) — Ctrl+C to exit

Step 2 — Add the server to Claude Code

Run this once in your terminal:

claude mcp add Dataverse --transport sse http://localhost:8199/sse

Verify it was added:

claude mcp list

You should see Dataverse in the list with status connected.

Step 3 — First sign-in (Claude Code)

In a Claude Code session, ask Claude to do something with Dataverse. Claude will call a Dataverse tool, get an authentication error, and automatically call Sign in to Dataverse. A sign-in URL will appear in the output — open it in your browser and sign in. Your browser will show "Authentication complete" when done. Tell Claude you've signed in and it will proceed with your request.

Stopping the server

docker compose down

Scope of MCP config in Claude Code

claude mcp add adds the server to your user-level config (~/.claude/config.json) by default, making it available in all Claude Code sessions on your machine. To scope it to a single project only:

claude mcp add Dataverse --transport sse http://localhost:8199/sse --scope project

This writes to .claude/config.json in the current directory instead.

---

Environment Variables

Variable	Required	Default	Description
DATAVERSE_URL	Yes	—	Your environment URL, e.g. https://yourorg.crm4.dynamics.com
CLIENT_ID	Yes	—	Azure AD Application (client) ID from your Entra ID app registration
TENANT_ID	No	common	Azure AD tenant ID — find it in Azure Portal → Microsoft Entra ID → Overview
AUTH_REDIRECT_PORT	No	5577	Port for the interactive auth redirect server

---

Token Cache

Cache files are stored as JSON on the persistent Docker volume with chmod 600 (owner read/write only). The container runs as a non-root user, so only the container process can access them. The Docker volume itself provides the isolation boundary.

If a cache file is corrupted: remove the Docker volume (docker volume rm dataverse-mcp_dataverse-data) and restart. The server logs a clear error and continues with an empty cache rather than crashing.

---

Example Conversations

Create an appointment:

"Schedule a meeting with the subject 'Q4 Review' tomorrow at 2pm for 1 hour, assigned to me"

Claude will automatically: call Get my identity (cached) → call Get table schema for appointment (cached after first use) → call Create record with correctly formatted fields.

Find contacts:

"Show me all contacts from Contoso"

Claude calls List records on the contacts table with an appropriate $filter.

Fix stale schema:

"The appointment fields seem wrong, can you refresh the schema?"

Claude calls Refresh schema cache for the appointment table, then re-fetches on the next schema request.

---

Security Notes

• Cache files are written with chmod 600 (owner read/write only)
• The container runs as a non-root user (mcpuser)
• No client secrets are stored anywhere — interactive flow uses only public client credentials
• Never commit .env to git — it is listed in .gitignore by default in this repo

---

Registering Your Own Azure AD App

Register an app in Azure Portal for your Dataverse MCP Server:

1. Go to Azure Portal → Microsoft Entra ID → App registrations → New registration
2. Name it anything (e.g. "Dataverse MCP Server")
3. Under Authentication, add platform Mobile and desktop applications
4. Add redirect URI: http://localhost:5577 (or your custom AUTH_REDIRECT_PORT)
5. Under API permissions, add Dynamics CRM → user_impersonation (delegated)
6. Copy the Application (client) ID into your .env as CLIENT_ID
7. Set TENANT_ID to your specific tenant ID for tighter security (avoids common)

---

Troubleshooting

"No valid token found" — The refresh token has expired (after 90 days of inactivity). Sign in again when prompted.

Claude Code: claude mcp list shows server as disconnected — The Docker container is not running. Run docker compose up -d (with the SSE override) before starting Claude Code.

"attribute does not exist" errors when creating records — The schema cache may be serving stale data. Ask Claude to call Refresh schema cache for the affected table, then retry.

Port 8199 already in use (Claude Code) — Change the port in docker-compose.sse.yml and update the claude mcp add URL accordingly.

Port 5577 refused during sign-in (macOS) — On macOS, docker compose run does not publish container ports by default. Add "--service-ports" to the args array in your claude_desktop_config.json (as shown in the configuration example above). If port 5577 is already allocated from a previous failed attempt, run docker compose down and remove stale containers before retrying.