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

Related MCP server: MCP Dataverse

Configuration

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

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.