Skip to main content
Glama

xpp-mcp

An MCP server for Dynamics 365 Finance and Operations X++ development. It reads and edits X++ artifacts, keeps .rnrproj/.sln files in step with them, and drives the Visual Studio that is already open on your solution for builds, live cross-references and database synchronization.

It needs two packages, and it does not work without both:

Package

What it is

Where it lives

@artman41/xpp-mcp-vs

The MCP server (Node.js, stdio). Its executable is xpp-mcp.

GitHub Packages (npm)

XppMcp.VsBridge.vsix

The Visual Studio extension. It lets the server talk to your open IDE over a per-user named pipe.

Attached to the v0.16.0 GitHub release

The server answers references, project membership, builds and sync from the running Visual Studio, so Visual Studio must be open with your X++ solution loaded.

Requirements

  • Windows, with PowerShell

  • Node.js 22 or later

  • Visual Studio 2022 (17.x; Community, Professional or Enterprise) with the Dynamics 365 Finance and Operations tools

  • .NET Framework 4.8

Related MCP server: FO Semantic MCP Server

Setup

1. Install the Visual Studio extension

Download the vsix (or take it from the release page) and install it:

Invoke-WebRequest https://github.com/artman41/xpp-mcp/releases/download/v0.16.0/XppMcp.VsBridge.vsix -OutFile XppMcp.VsBridge.vsix

Close Visual Studio, double-click the file and follow the installer, then reopen Visual Studio and your solution. The extension starts with Visual Studio and listens on a named pipe restricted to your Windows user.

2. Install the MCP server

The server is published to GitHub Packages, which needs a token even for public packages. Create a GitHub personal access token with the read:packages scope, then point the @artman41 scope at the registry and authenticate once:

npm config set "@artman41:registry" https://npm.pkg.github.com
npm config set "//npm.pkg.github.com/:_authToken" <your-token>
npm install -g "@artman41/xpp-mcp-vs"

The server and the extension must come from the same release; install the vsix matching the version you installed here.

3. Write a config file (optional)

Without a config file everything is read-only. Copy config.example.json (shipped in the package) somewhere and edit it:

{
  "dataDirectory": ".xpp-mcp/data",
  "policies": {
    "allowWrites": false,
    "allowBuilds": false,
    "allowDatabaseSynchronization": false,
    "allowEndpointMutations": false
  },
  "databaseSync": {
    "target": { "server": "localhost", "database": "AxDB" }
  }
}

Key

Meaning

policies.allowWrites

Allow source, project, solution and artifact changes to be written. Off: every mutating tool can only dry-run.

policies.allowBuilds

Allow build_project, build_solution and build_model to run.

policies.allowDatabaseSynchronization

Allow db_sync.

policies.allowEndpointMutations

Allow OData/DMF/custom-service mutations.

databaseSync.target

The only database a local sync may touch (server and database must match what Visual Studio reports).

databaseSync.allowCloudRuntime / finOpsUri

Opt-in for syncs against CloudRuntime / online environments.

timeouts, referenceIndex, build.maxOutputBytes

Bounds on processes, HTTP calls, result sizes and build output.

environment.connectCommand

Visual Studio command used to start the Dataverse connection wizard.

Paths in the config are resolved relative to the config file.

4. Register it with your MCP client

Any stdio MCP client works. For example, in a .mcp.json:

{
  "mcpServers": {
    "xpp": {
      "command": "xpp-mcp",
      "env": { "XPP_MCP_CONFIG": "C:\\path\\to\\config.json" }
    }
  }
}

Leave XPP_MCP_CONFIG out for the read-only defaults. Logs go to stderr; stdout carries only protocol messages.

With Visual Studio open on your solution, call server_status to confirm the server is running, then ide_solution_projects to confirm it can see the IDE.

What it provides

Every change defaults to a dry-run that returns a diff. Writes are validated first, use atomic replacement, and keep the file's encoding and newline style. A failed multi-file change leaves nothing half-applied.

Server

  • server_status: version, safety policies and configured resource counts.

  • resolve_path: resolve a file or directory visible to the solution loaded in Visual Studio.

Live Visual Studio queries

  • ide_solution_projects, ide_project_items: the projects, models and elements as the IDE sees them.

  • ide_references: find references from the IDE's live cross-reference store.

  • ide_definition: every model that defines an element, with layer and the element file.

  • ide_search: search artifact names of one AOT element type (Class, Table, Form, security roles and so on).

  • ide_type_relations: bases, derived classes, interface implementers and attribute users.

Reference graph

  • reference_tree, reference_resolve, reference_references: browse by package, model, type, artifact and member, and read typed incoming/outgoing edges.

  • reference_impact: bounded dependents or dependencies at artifact level.

  • reference_graph: class dependency graph with members and module boundaries.

  • reference_extensions: extension elements, chain-of-command classes, event handlers and delegate subscribers that hook into an artifact.

  • reference_labels: label ids (@File:Id) to text.

  • reference_reindex: rebuild a model's cross-reference data when queries come back empty.

  • reference_status, reference_refresh: freshness and provenance of the data; drop cached project membership.

Source files

  • source_read, source_parse, source_validate, source_write: read, parse and validate Dynamics XML and X++ (lexical and structural checks, not compiler-level semantics), and replace a file safely with an expected-hash conflict check.

Artifacts (68 fixture-backed types, for example Class, Table, Edt, Enum, Form, labels and resources)

  • artifact_registry: supported types and the ones that are unavailable.

  • artifact_design, artifact_build: generate XML and create the artifact, with optional .rnrproj membership.

  • artifact_validate, artifact_update: validate, update and rename, reconciling project memberships.

  • artifact_remove: remove after an impact report; needs confirm=true.

artifact_build creates the metadata files. It does not compile X++.

Projects and solutions

  • project_inspect, project_update: parse and validate .rnrproj files; create or update them with reconciled artifacts.

  • solution_inspect, solution_update: enumerate, add, remove and reorder X++ projects in a .sln, keeping dependencies and configuration rows in step.

Builds and database (run in the open Visual Studio; need allowBuilds / allowDatabaseSynchronization)

  • build_project, build_solution, build_model: compile with bounded diagnostics and logs. Builds are serialized.

  • db_sync: full database synchronization with preflight checks. A local sync only runs against databaseSync.target, and confirmDatabase must equal its name.

Environment

  • environment_info: the Dataverse / online F&O environment Visual Studio is connected to.

  • environment_connect: starts Visual Studio's own connection wizard and waits for you to finish signing in.

Troubleshooting

  • Tools report that Visual Studio is not available: Visual Studio is not running, the extension is not installed, or no solution is open. Reopen Visual Studio and check the extension is enabled under Extensions > Manage Extensions.

  • A write or build is refused: the matching policy in your config is still false.

  • Several Visual Studio instances: the server picks the one whose solution matches the target; open only the solution you are working on if it picks the wrong one.

Development

npm install
npm run build
npm run typecheck
npm run lint
npm test

CI (.github/workflows/ci.yml) runs lint and tests on every push and pull request, and publishes @artman41/xpp-mcp-vs to GitHub Packages on a push to master whose version is not published yet.

The extension source is in vs-extension/. It is not built in CI: it compiles against the Dynamics 365 Finance and Operations tools and Power Platform Tools assemblies from your local Visual Studio installation, which cannot be redistributed to a hosted runner. Build it on a machine that has them and attach the vsix to the GitHub release:

# override DynamicsToolsDir / PowerPlatformToolsDir if your Visual Studio edition is not Professional
msbuild vs-extension\XppMcp.VsBridge.csproj /restore /p:Configuration=Release

License

MIT. See LICENSE.

Available Tools

38 tools
artifact_buildB

Dry-run or create artifact XML and any label/resource payload, reconcile optional project membership; this does not compile X++.

Inputs: name (required), type (required), model (required), package (required), +9 more. Returns: ok, error, action, dryRun, +6 more

artifact_designC
Read-only

Generate a minimal fixture-shaped XML design without reading or writing files.

Inputs: name (required), type (required). Returns: id, ok, error, content, +1 more

artifact_registryB
Read-only

List all fixture-backed artifact metadata and explicitly unavailable types.

Inputs: no named parameters. Returns: ok, error, artifacts, unavailable

artifact_removeA
Destructive

Dry-run or remove artifact XML, any companion payload, and indexed project memberships after impact analysis; actual removal requires confirm=true.

Inputs: path (required), root, limit, dryRun, +7 more. Returns: ok, error, action, dryRun, +6 more

artifact_updateB
Destructive

Dry-run or validate and update/rename artifact XML and any companion payload, reconciling indexed project memberships in one transaction.

Inputs: path (required), content (required), root, dryRun, +7 more. Returns: ok, error, action, dryRun, +6 more

artifact_validateB
Read-only

Validate a supported artifact's XML, X++, registry shape, identity, filename, and companion metadata.

Inputs: path (required), root. Returns: ok, kind, path, root, +9 more

build_modelB

Dry-run or compile a Dynamics 365 model in the open Visual Studio (Dynamics 365 > Build Models) and bounded logs.

Inputs: model (required), package (required), dryRun, options, +3 more. Returns: ok, cwd, args, kind, +18 more

build_projectB

Dry-run or compile an X++ .rnrproj in the open Visual Studio.

Inputs: path (required), root, dryRun, logLevel, +3 more. Returns: ok, cwd, args, kind, +18 more

build_solutionB

Dry-run or compile the X++ projects of the solution open in Visual Studio.

Inputs: path (required), root, dryRun, logLevel, +3 more. Returns: ok, cwd, args, kind, +18 more

db_syncA
DestructiveIdempotent

Dry-run or run a full database synchronization through Visual Studio. Always runs preflight checks. A local runtime syncs only databaseSync.target (confirmDatabase must equal its database name). A CloudRuntime environment syncs only databaseSync.finOpsUri, which must be the environment Visual Studio is connected to (confirmEnvironment must equal its host); it needs databaseSync.allowCloudRuntime and a connection confirmed this session, and never opens a connection wizard. A real run also needs policies.allowDatabaseSynchronization and dryRun=false. The online sync reports no result of its own, so the extension watches the Power Platform output for the Dataverse async operation status (30 succeeded, 31 failed, 32 canceled); success is null if none appears before timeoutMs.

Inputs: dryRun, timeoutMs, confirmDatabase, confirmEnvironment. Returns: ok, mode, error, ready, +15 more

environment_connectA
Idempotent

Start Visual Studio's own Connect to Dataverse command and wait for the user to complete the interactive sign-in and solution selection in Visual Studio, then describe the connected environment. The sign-in itself cannot be automated.

Inputs: timeoutMs. Returns: ok, busy, error, finOps, +4 more

environment_infoA
Read-only

Describe the Dataverse / online Finance and Operations environment Visual Studio is connected to (URLs, type, versions, tenant, busy flag). If Visual Studio is not connected it opens its connection wizard, so this refuses unless allowPrompt is true or a connected environment was already seen in this session. No access token is ever returned.

Inputs: allowPrompt. Returns: ok, busy, error, finOps, +4 more

ide_definitionB
Read-only

Resolve where an element is defined according to the open Visual Studio: every model that defines it (with layer and module) and the element file in each.

Inputs: name (required), type (required). Returns: ok, error, models

ide_project_itemsB
Read-only

List the elements of a project as the IDE sees them, optionally filtered by artifact type such as Class, Table, Form or Edt.

Inputs: path (required), root, type. Returns: ok, error, items

ide_referencesB
Read-only

Find references to an element using the live cross-reference store of the open Visual Studio (not a stale archive). Targets use cross-reference paths such as /Classes/Name, /Classes/Name/Methods/method or /Tables/Name.

Inputs: target (required), kind, limit, source. Returns: ok, error, truncated, references

ide_solution_projectsA
Read-only

List the projects (and their models) of the solution open in Visual Studio, as the IDE sees them.

Inputs: no named parameters. Returns: ok, error, models, projects, +1 more

ide_type_relationsB
Read-only

Class relationships from the open Visual Studio: bases (inheritance chain), derived (classes extending it), implementers (classes implementing an interface) or attributed (classes carrying an attribute).

Inputs: name (required), relation (required), limit. Returns: ok, error, names, truncated

project_inspectB
Read-only

Parse and validate an .rnrproj, including artifact membership against the reference index.

Inputs: path (required), root. Returns: ok, guid, name, path, +6 more

project_updateC
Destructive

Dry-run or create/update an .rnrproj with reconciled artifacts and optional solution registration.

Inputs: name (required), path (required), model (required), artifacts (required), +7 more. Returns: ok, error, dryRun, changes, +1 more

reference_extensionsA
Read-only

List what extends an artifact: its extension elements (TableExtension, FormExtension, EnumExtension... named .), chain-of-command classes ([ExtensionOf]), event handlers ([DataEventHandler], [FormEventHandler], [FormDataSourceEventHandler], [FormControlEventHandler], [FormDataFieldEventHandler], [PreHandlerFor], [PostHandlerFor]) and delegate subscribers ([SubscribesTo]) that name the artifact or one of its members. Use it before changing an artifact to see the code that hooks into it.

Inputs: id (required), limit. Returns: id, ok, error, elements, +3 more

reference_graphA
Read-only

Build a dependency graph between classes from the IDE's cross-reference store: starting from root classes, follow outgoing dependencies or incoming dependents up to a depth. Edges are folded to artifact level and list the methods/members involved; edges between different modules are flagged and summarized as boundaries. Only classes are expanded further; tables, EDTs, enums and others appear as leaves.

Inputs: roots (required), kind, depth, maxNodes, +2 more. Returns: ok, edges, error, nodes, +3 more

reference_impactC
Read-only

Traverse bounded incoming dependents or outgoing dependencies at artifact granularity.

Inputs: id (required), depth, limit, direction. Returns: ok, error, items, freshness, +1 more

reference_labelsA
Read-only

Resolve label ids (@File:LabelId, or legacy @SYS12345) to their text in one language, from the label files Visual Studio knows. text is null when the label file or label is not found (Microsoft label files shipped only as binaries are not readable).

Inputs: ids (required), language. Returns: ok, error, labels

reference_referencesA
Read-only

Read bounded incoming or outgoing typed reference edges for an artifact or member, from the IDE's cross-reference store. An artifact id (/Tables/CustTable) covers every nested member (fields, methods, field groups, form data sources and controls...), its extensions (CustTable.) and metadata links such as menu item -> form, security privilege -> menu item, query/entity/form field bindings and EDT relations (provider ide-xref-metadata, paths dynamics://Type/Name/...?Property). A member id (/Tables/CustTable/Fields/AccountNum, /Forms/F/DataSources/D/DataFields/F, /Forms/F/Controls/C) narrows to that member. Label targets carry their en-US text. Empty results can mean the cross-reference data was never built for the referencing model: run reference_reindex on it and retry.

Inputs: id (required), direction (required), kind, limit, +1 more. Returns: ok, error, items, limit, +5 more

reference_refreshA
Read-only

Drop the cached project-membership data so the next reference query reads Visual Studio again.

Inputs: no named parameters. Returns: ok, error, freshness

reference_reindexA

Rebuild the Visual Studio cross-reference data for a model (cross-reference-only model build, no compile). Use it when reference_references/reference_impact/reference_graph return nothing for code you know exists, e.g. fields or methods added in an extension model: reindex the model that holds the referencing code, then query again. Needs policies.allowBuilds.

Inputs: model (required), dryRun, timeoutMs. Returns: ok, cwd, args, kind, +18 more

reference_resolveC
Read-only

Resolve an artifact or member by canonical ID or case-insensitive name.

Inputs: query (required), type, limit, member, +1 more. Returns: ok, error, items, limit, +5 more

reference_statusA
Read-only

Read the freshness and provenance of the reference data (live from Visual Studio).

Inputs: no named parameters. Returns: ok, error, freshness

reference_treeC
Read-only

Inspect the reference tree by package, model, artifact type, artifact, and member.

Inputs: limit, offset, parent. Returns: ok, error, items, limit, +5 more

resolve_pathC
Read-only

Resolve an existing file or directory visible to the solution loaded in Visual Studio.

Inputs: path (required), root, operation. Returns: ok, kind, path, error, +1 more

server_statusA
Read-only

Read server version, safety policies, and configured resource counts.

Inputs: no named parameters. Returns: ok, error, scope, version, +3 more

solution_inspectB
Read-only

Enumerate and validate X++ and other projects in a Visual Studio .sln file.

Inputs: path (required), root. Returns: ok, path, error, valid, +3 more

solution_updateC
Destructive

Dry-run or add, remove, or reorder X++ projects with dependency and configuration reconciliation.

Inputs: path (required), action (required), root, dryRun, +4 more. Returns: ok, error, dryRun, changes

source_parseB
Read-only

Parse Dynamics XML or X++ source and return artifact members, source references, and diagnostics.

Inputs: path (required), root. Returns: ok, kind, path, root, +7 more

source_readB
Read-only

Read a bounded .xml or .xpp source file with its encoding, newline style, and SHA-256.

Inputs: path (required), root. Returns: ok, bom, kind, path, +6 more

source_validateB
Read-only

Validate XML well-formedness, Dynamics artifact identity, and lexical X++ structure.

Inputs: path (required), root. Returns: ok, kind, path, root, +8 more

source_writeA
Destructive

Dry-run or atomically replace an existing source file after validation, preserving encoding and newlines.

Inputs: path (required), content (required), root, dryRun, +1 more. Returns: ok, diff, path, error, +6 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 38 tools

    Disambiguation3/5

    Prefix grouping helps, but several tools target nearly the same question through different backends: reference_references vs ide_references (both find references), reference_impact vs reference_graph vs ide_type_relations (all dependency traversal), and solution_inspect vs ide_solution_projects vs project_inspect vs ide_project_items (project/solution enumeration). The descriptions do explain the distinction (cached xref store vs live IDE, artifact vs class granularity), so an attentive agent can pick, but the boundaries require careful reading.

    Naming Consistency4/5

    Clear domain prefixes (reference_, source_, project_, solution_, artifact_, build_, ide_, environment_, db_) followed by verb or noun, mostly verb_noun (source_parse, artifact_validate, build_model). A few noun-only outliers (reference_tree, artifact_registry, environment_info) and the mix of project_/solution_/ide_ prefixes for overlapping concepts are minor deviations rather than a breakdown.

    Tool Count2/5

    38 tools is well past the 25-tool threshold and a handful are near-redundant or thin utility calls (reference_refresh, reference_status, server_status, resolve_path, artifact_registry) that inflate the surface. The domain is genuinely broad (xref, IDE, source, project, artifact, build, environment, DB), but the set could be consolidated meaningfully.

    Completeness4/5

    Coverage is strong: read/parse/validate/write for sources, design/build/update/remove for artifacts, inspect/update for projects and solutions, three build scopes, cross-reference querying and reindexing, plus environment and DB sync. Minor gaps remain — no delete/rename for projects or solutions, no test execution or rollback, and no explicit 'list artifacts in project' beyond ide_project_items.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables D365 F\&O development including object creation, modification, deletion, and analysis through the MCP standard.
      42
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to search and analyze Microsoft Dynamics 365 Finance & Operations artifacts, read local source code, and generate context-aware solutions through natural language.
      71 npm
      12
      -
    • A
      license
      A
      quality
      A
      maintenance
      Enables AI-assisted X++ development for Dynamics 365 Finance and Operations by pre-indexing the entire codebase and providing 54 specialized tools for metadata lookup, code generation, and best practice validation.
      20
      459 npm
      173
      MIT