odatav4-mcp

An MCP (Model Context Protocol) server for OData v4 endpoints, tuned for Microsoft Dataverse / Dynamics 365 but usable with any OData v4 service.

• Zero-registration auth: signs in with Entra ID using the well-known Microsoft public client (51f81489-12ee-4a9e-aac9-25749fb2a1de, the same app XrmToolBox and the Dataverse samples use). The default flow opens your browser with a localhost redirect (works where Conditional Access blocks device-code flow); device-code flow is available for headless/SSH sessions. MFA works; tokens are cached on disk so you sign in once, not per session.
• One config value: just the endpoint URL.
• Full OData surface: metadata discovery, queries ($filter/$select/$expand/ $apply/$count), paging, CRUD, associations, functions/actions, and a raw request escape hatch.

Install

git clone <this-repo> odatav4-mcp
cd odatav4-mcp
npm install        # also compiles TypeScript (prepare script)

Optional but recommended — sign in once from a terminal so the MCP client never has to relay sign-in instructions:

ODATA_URL=https://yourorg.crm.dynamics.com npm run login
# headless / SSH (no local browser):
ODATA_URL=https://yourorg.crm.dynamics.com npm run login -- --devicecode

Configuration

Env var	Required	Description
ODATA_URL	yes	Service root. A bare Dataverse org URL (https://yourorg.crm.dynamics.com) is expanded to /api/data/v9.2/ automatically.
ODATA_TENANT	no	Tenant id or domain (default organizations). Set this if your account exists in multiple tenants.
ODATA_CLIENT_ID	no	Override the Entra app id (default: the well-known Dataverse dev-tools client).
ODATA_LOGIN_FLOW	no	interactive (default: opens a browser, localhost redirect) or devicecode (enter a code at microsoft.com/devicelogin — for headless/SSH, or if your tenant blocks the browser flow).
ODATA_AUTH	no	Set to none for anonymous OData services (e.g. public test services).
ODATA_CACHE_DIR	no	Where tokens and $metadata are cached (default ~/.config/odatav4-mcp/<host>).

Hook up to your client

Use the absolute path to dist/index.js in all cases.

GitHub Copilot (VS Code)

Create .vscode/mcp.json in your workspace (or add via MCP: Add Server):

{
  "servers": {
    "dataverse": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/odatav4-mcp/dist/index.js"],
      "env": { "ODATA_URL": "https://yourorg.crm.dynamics.com" }
    }
  }
}

Claude Code

claude mcp add dataverse --env ODATA_URL=https://yourorg.crm.dynamics.com -- node /path/to/odatav4-mcp/dist/index.js

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.dataverse]
command = "node"
args = ["/path/to/odatav4-mcp/dist/index.js"]
env = { ODATA_URL = "https://yourorg.crm.dynamics.com" }

Tools

Tool	Purpose
login, auth_status, logout	Device-code sign-in and token management
service_info, whoami	Connection status; Dataverse WhoAmI
list_entity_sets, describe_entity, list_operations	Schema discovery from $metadata (cached 6h)
query, next_page, get_record	Reads with full OData query options and paging
create_record, update_record, delete_record	CRUD (update sends If-Match: * to prevent accidental upserts)
associate_records, disassociate_records	N:N / collection navigation $ref operations
call_function, call_action	OData functions (GET) and actions (POST), bound or unbound — covers Dataverse messages and custom APIs
raw_request	Any other request, restricted to the configured host

Notes

• Auth flow: silent token refresh from the on-disk MSAL cache first; if that fails, tools return an instruction to run the login tool. By default that opens your system browser (on WSL it launches the Windows browser via wslview or rundll32.exe) and completes through a localhost redirect; MSAL runs the loopback listener automatically. The login tool accepts {"flow": "devicecode"} to switch flows per call. Both flows are attempted against the same well-known client id, which has http://localhost registered as a redirect URI.
• The token cache (msal-cache.json) contains refresh tokens; it is written with mode 600 into your home config directory. Delete it (or use logout) to revoke local access.
• Dataverse $metadata is large (10 MB+); it is cached on disk for 6 hours. Pass refresh: true to list_entity_sets to force a re-download.