almxppmcp

npx launcher for the ALM XPP MCP cloud server - a D365 Finance & Operations AI Agent with 34 tools.

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

| Variable | Description | |---|---| | ALMXPPMCP_API_KEY | Your API token (alternative to --api-key) | | ALMXPPMCP_SERVER_URL | Override the MCP endpoint (default: https://api.almxpp.com/mcp) |

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:

| Variable | Description | |---|---| | D365FO_MCP_URL | Full remote MCP URL, for example https://your-env.sandbox.operations.dynamics.com/mcp | | D365FO_RESOURCE | D365FO resource URL, for example https://your-env.sandbox.operations.dynamics.com | | D365FO_TENANT_ID | Optional tenant override for Azure CLI token acquisition |

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:

| Variable | Description | |---|---| | D365FO_PROXY_URL | Hosted ALM XPP proxy endpoint, for example https://www.almxpp.com/api/d365fo/mcp | | D365FO_PROXY_API_KEY | ALM XPP API token used to call the hosted proxy | | D365FO_MCP_URL | Optional but recommended per-user target environment URL | | D365FO_RESOURCE | Optional but recommended per-user resource URL |

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 server exposes 34 tools across 6 categories:

| Category | Tools | |---|---| | Discovery | search_d365_code, get_object_details, list_objects, get_relation_graph, find_related_objects | | References & Impact | find_references, find_extensions, find_callers | | Code Generation | generate_xpp_template, generate_query, generate_d365_solution, generate_unit_test | | Quality & Validation | validate_best_practices, detect_performance_issues, validate_aot_pattern, explain_code_complexity, suggest_refactoring | | Security & Licensing | trace_security_chain, trace_role_license_tree, generate_security_governance_report | | Azure DevOps | ado_query_workitems, ado_create_task, ado_list_prs, ado_analyze_pr_impact, ado_post_comment, ado_post_pr_comment, ado_changelog_from_prs, ado_analyze_workitem, ado_estimate_effort, ado_auto_test_scenario, ado_gap_fit_analysis, ado_knowledge_gap_detector, ado_sprint_capacity |

See the dashboard for the full tool list.

License

MIT