xpp-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xpp-mcp find all references to SalesTable in my open solution"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| The MCP server (Node.js, stdio). Its executable is | GitHub Packages (npm) |
| The Visual Studio extension. It lets the server talk to your open IDE over a per-user named pipe. | Attached to the |
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.vsixClose 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 |
| Allow source, project, solution and artifact changes to be written. Off: every mutating tool can only dry-run. |
| Allow |
| Allow |
| Allow OData/DMF/custom-service mutations. |
| The only database a local sync may touch ( |
| Opt-in for syncs against CloudRuntime / online environments. |
| Bounds on processes, HTTP calls, result sizes and build output. |
| 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.rnrprojmembership.artifact_validate,artifact_update: validate, update and rename, reconciling project memberships.artifact_remove: remove after an impact report; needsconfirm=true.
artifact_build creates the metadata files. It does not compile X++.
Projects and solutions
project_inspect,project_update: parse and validate.rnrprojfiles; 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 againstdatabaseSync.target, andconfirmDatabasemust 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 testCI (.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=ReleaseLicense
MIT. See LICENSE.
Available Tools
38 toolsartifact_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_designCRead-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_registryBRead-only
List all fixture-backed artifact metadata and explicitly unavailable types.
Inputs: no named parameters. Returns: ok, error, artifacts, unavailable
artifact_removeADestructive
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_updateBDestructive
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_validateBRead-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_syncADestructiveIdempotent
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_connectAIdempotent
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_infoARead-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_definitionBRead-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_itemsBRead-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_referencesBRead-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_searchARead-only
Search the artifact names of one AOT element type (Class, Table, Form, MenuItemDisplay, SecurityRole, DataEntityView, Service, ...: the Application Explorer node type) across the models visible to the loaded solution, including Microsoft dependency models, using the IDE's metadata. pattern is a case-insensitive regular expression; omit it to list names.
Inputs: type (required), limit, pattern. Returns: ok, error, items, truncated
ide_solution_projectsARead-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_relationsBRead-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_inspectBRead-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_updateCDestructive
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_extensionsARead-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_graphARead-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_impactCRead-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_labelsARead-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_referencesARead-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_refreshARead-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_resolveCRead-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_statusARead-only
Read the freshness and provenance of the reference data (live from Visual Studio).
Inputs: no named parameters. Returns: ok, error, freshness
reference_treeCRead-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_pathCRead-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_statusARead-only
Read server version, safety policies, and configured resource counts.
Inputs: no named parameters. Returns: ok, error, scope, version, +3 more
solution_inspectBRead-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_updateCDestructive
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_parseBRead-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_readBRead-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_validateBRead-only
Validate XML well-formedness, Dynamics artifact identity, and lexical X++ structure.
Inputs: path (required), root. Returns: ok, kind, path, root, +8 more
source_writeADestructive
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
Scored across 38 tools
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.
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.
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.
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
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Generate wiki docs from source code. Supports PowerShell, Python, Go, C#, Java, COBOL.
Change-impact intelligence for tracing dependencies, stale references and required updates.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables D365 F\&O development including object creation, modification, deletion, and analysis through the MCP standard.42MIT
- FlicenseNot gradedqualityCmaintenanceEnables 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 npm12-
- AlicenseAqualityAmaintenanceEnables 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.20459 npm173MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding assistants to ground on real D365 F&O AOT metadata locally and offline, preventing hallucinated X++ field names and Chain of Command signatures.MIT