almxppmcp

npx launcher for the ALM XPP MCP cloud server - a Dynamics 365 Finance & Operations AI agent exposing 90 tools over MCP.

The server answers from a pre-built index of the standard D365 F&O codebase: 200K+ AOT objects, 1.3M+ code chunks, 25M+ cross-references and 392K+ labels indexed in every language.

Requirements

• Node.js >= 18
• An API token -- get one at the dashboard

Quick Start

npx almxppmcp --api-key YOUR_TOKEN

or set the environment variable:

export ALMXPPMCP_API_KEY=YOUR_TOKEN
npx almxppmcp

MCP Client Configuration

VS Code / GitHub Copilot -- .vscode/mcp.json

{
  "servers": {
    "almxppmcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "almxppmcp", "--api-key", "YOUR_TOKEN"]
    }
  }
}

Cursor -- .cursor/mcp.json

{
  "mcpServers": {
    "almxppmcp": {
      "command": "npx",
      "args": ["-y", "almxppmcp", "--api-key", "YOUR_TOKEN"]
    }
  }
}

Claude Desktop -- claude_desktop_config.json

{
  "mcpServers": {
    "almxppmcp": {
      "command": "npx",
      "args": ["-y", "almxppmcp", "--api-key", "YOUR_TOKEN"]
    }
  }
}

Tip: replace YOUR_TOKEN with the token shown on your dashboard. Set it as an env var to avoid hard-coding it:

{
  "mcpServers": {
    "almxppmcp": {
      "command": "npx",
    "args": ["-y", "almxppmcp"],
      "env": { "ALMXPPMCP_API_KEY": "YOUR_TOKEN" }
    }
  }
}

Environment Variables

Dedicated D365FO Data Environment

Use the bundled almxppmcp-d365fo-proxy when you want a second MCP server dedicated to the live D365FO environment data layer.

It now supports both modes:

• local direct mode: your machine gets the D365FO token with Azure CLI and calls the environment directly
• cloud bridge mode: the launcher calls your hosted ALM XPP endpoint, which acquires the D365FO token server-side

This is intentionally separate from almxppmcp:

• almxppmcp: KB, custom code, relations, Azure DevOps, generation
• almxppmcp-d365fo-proxy: live D365FO environment MCP endpoint over Azure CLI auth

What it does

• runs as a local stdio MCP server for Copilot, Cursor, or Claude
• fetches Azure AD bearer tokens with az account get-access-token
• forwards JSON-RPC messages to the D365FO remote MCP endpoint
• preserves mcp-session-id across requests
• handles plain JSON and text/event-stream responses

Local direct mode

Required environment variables:

Example VS Code MCP configuration:

{
  "servers": {
    "almxppmcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "almxppmcp"],
      "env": {
        "ALMXPPMCP_API_KEY": "YOUR_TOKEN"
      }
    },
    "d365fo-data": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "almxppmcp", "almxppmcp-d365fo-proxy"],
      "env": {
        "D365FO_MCP_URL": "https://YOUR-ENV.sandbox.operations.dynamics.com/mcp",
        "D365FO_RESOURCE": "https://YOUR-ENV.sandbox.operations.dynamics.com"
      }
    }
  }
}

Cloud bridge mode

Required environment variables:

In multi-user scenarios, keep the environment URL in each user's MCP config (not in ACA global variables). The launcher forwards these values to the cloud bridge per request.

Example VS Code MCP configuration:

{
  "servers": {
    "d365fo-data": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "-p", "almxppmcp", "almxppmcp-d365fo-proxy"],
      "env": {
        "D365FO_PROXY_URL": "https://www.almxpp.com/api/d365fo/mcp",
        "D365FO_PROXY_API_KEY": "YOUR_ALMXPP_TOKEN",
        "D365FO_MCP_URL": "https://YOUR-ENV.sandbox.operations.dynamics.com/mcp",
        "D365FO_RESOURCE": "https://YOUR-ENV.sandbox.operations.dynamics.com"
      }
    }
  }
}

D365FO prerequisites

1. Install Azure CLI and run az login
2. In D365FO, open Allowed MCP clients
3. Add Azure CLI client id 04b07795-8ddb-461a-bbee-02f9e1bf7b46
4. Mark it as allowed for the target environment

Note:

• this universal client id is configured in D365 only
• do not put this client id in MCP JSON
• MCP JSON only needs the proxy command and the relevant URL/env values

Recommended usage pattern

Use the two MCP servers together:

• ask almxppmcp to identify the table, entity, relations, custom extensions, and related work items
• ask d365fo-data to inspect the real environment data, forms, or custom actions
• cross the results in the chat to connect KB, custom code, work items, and live data

See npm/examples/vscode-mcp.d365fo-data.json, npm/examples/vscode-mcp.d365fo-data.cloud.json, and docs/D365FO_DATA_ENVIRONMENT_SETUP.md for ready-to-use setups.

What tools are available?

The cloud server exposes 90 tools across 14 categories. A companion local server adds 58 more for anything that must run next to your D365 environment (build, deploy, database sync, workspace writes).

Beyond code search, the notable capabilities are:

• Upgrade impact - compare two D365 versions against your own customisations and produce the regression report as Word and PowerPoint.
• Live environment - connect to a running environment, read and write real records over OData, run Data Management projects.
• Performance diagnostics - query Application Insights telemetry and get a ranked diagnosis of what is actually slow.
• Azure DevOps - work items, pull requests, wiki, from analysis to review.

Full reference with parameters and example prompts: https://www.almxpp.com/docs

What is in this repository

This repository holds the client side only — the npx launcher published to npm as almxppmcp:

The server itself — index, retrieval, the 148 tools and the licensing layer — is closed source and runs at https://www.almxpp.com/mcp. The launcher never sees your code: it forwards requests over HTTPS with the token you provide.

License

MIT