almxppmcp

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

Published in the official MCP registry as io.github.alimbenhelal-pro/alm-xpp-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 24M+ label translations -- 392K label ids rendered across 74 languages.

Why an index rather than a general-purpose model

A general model answers X++ questions from whatever it memorised during training. This server answers from a specific, versioned copy of the standard D365 codebase:

| | What it means in practice | |---|---| | A known release | The Cloud MCP answers from the release the server has indexed, not from yours. The one currently loaded is reported by GET /mcp -- check it before relying on a version-sensitive answer | | Your own version | Indexing your environment's exact build is what the Local MCP is for: it runs next to your D365 SDK and indexes the PackagesLocalDirectory on that machine. The Cloud MCP cannot do this -- it never sees your platform binaries | | Traceable | Every result carries the AOT object and model it came from, so you can open it in Visual Studio and check | | Your extensions | Point D365-Custom-Model-Path at your metadata, or let it index your Azure DevOps repository, and your own code is searched alongside the standard code | | No training on your code | Your metadata is indexed per session and used to answer your calls. It is not used to train anything |

Three servers, three roles

Three different MCP servers show up around D365 F&O. This README always calls them by these names:

| Name | What it is | How you get it | |---|---|---| | Cloud MCP | The hosted ALM XPP server: 90 tools over the indexed D365 codebase | this package -- npx almxppmcp | | Local MCP | Runs on your own dev machine, next to the D365 SDK: 121 tools, 36 of which write AOT files, compile X++, sync the database. It is also the only one that can index your exact platform build, by reading the PackagesLocalDirectory on that machine | separate licensed component, contact [email protected] | | Environment MCP | Microsoft's own Dynamics 365 ERP MCP server, exposed by your F&O environment itself, serving live data | enabled inside D365FO, then connected directly from VS Code |

This npm package covers the Cloud MCP only. The Local MCP is licensed separately, and the Environment MCP is Microsoft's -- your client connects to it on its own.

Requirements

• An API token -- get one at the dashboard
• Node.js >= 18, only if you use the npx launcher described further down

MCP Client Configuration

The Cloud MCP is a streamable HTTP MCP server at https://api.almxpp.com/mcp, authenticated with the X-API-Key header. Any client that speaks HTTP connects to it directly -- no Node.js, no launcher.

Tool calls are served on api.almxpp.com only. almxpp.com and www.almxpp.com host the website; a JSON-RPC POST sent there is refused with a message naming the correct URL. Only the host changes -- your API key and headers stay the same.

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

{
  "servers": {
    "almxppmcp": {
      "type": "http",
      "url": "https://api.almxpp.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_TOKEN"
      }
    }
  }
}

Headers

X-API-Key is the only required header. The others unlock the tools that need your own context -- without them those tools simply report that they are not configured.

| Header | Unlocks | |---|---| | X-API-Key | Required. Your API token. Authorization: Bearer <token> works too. | | D365-Custom-Model-Path | Absolute path to your own extension / ISV metadata on the calling machine. Analysis tools read from here | | D365-Standard-Model-Path | Absolute path to PackagesLocalDirectory, used as a read-only reference for standard objects | | DEVOPS_ORG_URL | Azure DevOps organisation, e.g. https://dev.azure.com/MyOrg | | DEVOPS_PROJECT | Azure DevOps project name. Required alongside DEVOPS_ORG_URL. | | DEVOPS_PAT | Azure DevOps token. Indexes your own X++ metadata from the repo and reads work items. | | DEVOPS_REPO | Repository holding the metadata, when the project has several | | DEVOPS_BRANCH | Branch to index, default main | | DEVOPS_METADATA_PATH | Folder inside the repo holding the AOT XML, default Metadata | | D365FO-Url | Live environment base URL, for the odata_* and dmf_* tools | | D365FO-Tenant-Id | Entra tenant of that environment | | D365FO-Client-Id | Entra app registered in D365FO under Microsoft Entra applications | | D365FO-Client-Secret | Secret of that app | | AppInsights-Workspace-Id | Log Analytics workspace, for the appinsights_* tools | | AppInsights-Tenant-Id | Entra tenant of that workspace | | AppInsights-Client-Id | Entra app with Log Analytics Reader on the workspace | | AppInsights-Client-Secret | Secret of that app |

The live-environment and telemetry credentials can also be set for the session with d365fo_set_connection and appinsights_set_connection, so they never sit in a config file.

examples/vscode-mcp.full-headers.json puts all of this together and keeps every secret out of the file by prompting for it through VS Code inputs.

The npx launcher

Some clients only speak stdio. The almxppmcp command covers that case: it reads your token, sends it as the X-API-Key header, and relays the traffic to the Cloud MCP over stdio. It has no dependencies -- just the one file, on top of what Node 18 already provides.

npx almxppmcp --api-key YOUR_TOKEN

or set the environment variable:

export ALMXPPMCP_API_KEY=YOUR_TOKEN
npx almxppmcp

--api-key and ALMXPPMCP_API_KEY are the two ways of giving the token to the launcher. Either way it ends up on the wire as the HTTP header X-API-Key -- same token, different layer.

VS Code, if you prefer the launcher -- .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 (root key is mcpServers for Cursor and Claude Desktop, servers for VS Code):

{
  "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) |

What tools are available?

The Cloud MCP exposes 90 tools across 14 categories, listed below.

The Local MCP carries the 85 of them that do not depend on the cloud index, plus 36 more that must run next to your D365 environment (build, deploy, database sync, workspace writes) -- 121 tools on that side. Across both servers the toolbox is 126 distinct tools.

| Category | Tools | Names | |---|---:|---| | Search | 5 | search_d365_code, search_labels, batch_search, federated_search, search_context_docs | | Retrieve | 6 | get_object_details, list_objects, list_custom_model_objects, get_object_context, compare_objects, get_menu_item_info | | Relations & Impact | 11 | find_related_objects, find_references, find_extensions, get_relation_graph, find_entity_for_table, find_callers, find_change_impact, find_event_handlers, find_relation_path, find_similar_implementations, trace_field_lineage | | Quality & Analysis | 7 | validate_best_practices, detect_performance_issues, find_error_patterns, fix_best_practice_violations, recommend_extension_strategy, suggest_edt, validate_object_naming | | Security & Licensing | 4 | trace_security_chain, trace_role_license_tree, get_security_coverage_for_object, generate_security_report | | Code Generation | 8 | generate_unit_test, suggest_refactoring, generate_diagram, generate_query, create_aot_object, generate_data_entity, generate_xpp_form, generate_xpp_template | | Functional Domain | 2 | generate_fdd, explain_workflow | | Differentiators | 2 | analyze_upgrade_impact, map_business_process | | Upgrade & Release Notes | 6 | resolve_client_profile, save_client_profile, list_release_note_inputs, prepare_release_note_context, generate_release_note_document, diff_model_versions | | Live Environment | 5 | d365fo_set_connection, d365fo_clear_connection, odata_export_entity, odata_upsert_rows, get_data_entity_info | | Data Migration | 7 | dmf, dmf_create_data_project, dmf_apply_entity_filter, dmf_import_file, dmf_export_package, dmf_get_job_status, dmf_transform_excel | | Performance Diagnostics | 4 | appinsights_set_connection, appinsights_clear_connection, appinsights_query, appinsights_diagnose_slowness | | Orchestration & Reporting | 6 | plan_and_execute, summarize_for_stakeholder, resolve_workspace_roots, resync_devops_index, healthcheck, get_output_page | | Azure DevOps | 17 | ado_query_workitems, ado_analyze_workitem, ado_list_prs, ado_analyze_pr_impact, ado_gap_fit_analysis, ado_estimate_effort, ado_post_comment, ado_post_pr_comment, ado_create_task, ado_read_attachment, ado_update_workitem, ado_review_xpp_pr, ado_pr_dependency_map, ado_wiki_list, ado_wiki_get_page, ado_wiki_create_or_update_page, ado_wiki_delete_page |

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:

| Path | Purpose | |---|---| | bin/almxppmcp.js | Resolves the API key and server URL, then bridges your client's stdio to the Cloud MCP over HTTP -- no third-party package involved | | server.json | MCP registry manifest |

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

License

MIT