@darkloop/veyo-mcp

v1.1.10

Published

7 days ago

Veyo MCP — Model Context Protocol server for Business Central/NAV codebase analysis

0High
0Medium
0Low

bananoo

mcp veyo business-central nav dynamics-nav model-context-protocol

Veyo MCP — Code Intelligence for Business Central & Dynamics NAV

@darkloop/veyo-mcp is the Model Context Protocol server that gives any MCP-compatible AI assistant — Claude, ChatGPT, GitHub Copilot, Cursor, Windsurf, and more — exact, version-aware context about your Business Central (AL) and Dynamics NAV (C/AL) codebase.

Generic LLMs know Business Central in theory. They don't know your version, your cumulative updates, or the years of custom AL/C-AL that actually run your business — so they invent procedure signatures, miss event subscribers, and suggest upgrades that break production. Veyo fixes that by giving the model your real, parsed codebase through 14 purpose-built query tools.

🔑 Veyo MCP requires a subscription
This package connects to the Veyo cloud service, which needs an active subscription and an API key.
Start a free trial at www.veyomcp.com — cancel anytime, no charge until the trial ends.
Sign up and generate your API key in the Veyo Cloud Portal →

What you get

Every subscription includes:

Cloud — standard BC base application. Instant access to the official Business Central base app code. Every version (BC14 → BC26), multiple locales, kept current on the latest cumulative update. Nothing to install.
On-premise — your custom code. An included edition you deploy on your own infrastructure to parse your custom objects, extensions, and legacy Dynamics NAV C/AL — your source code never leaves your network.
14 query tools exposed over MCP, every answer grounded in your version rather than the internet's.

Built for every role on a BC team

Veyo gives your AI assistants the structured context they need so your people can stop guessing and start delivering — whatever their role.

| Role | What Veyo unlocks | Tools they reach for | |------|-------------------|----------------------| | Support | Resolve issues faster with codebase context. Trace exactly where the relevant logic lives in that client's project — which subscribers fire, what extensions modify standard behaviour, how data flows — instead of hours of manual searching. | event_flow_tracker · procedure_lister · extension_finder · page_field_analyzer | | Consultancy | Configure with confidence, not guesswork. Explain how procedures, events, and table relationships work in the client's specific BC version, locale, and CU. Scope customisations and integration touchpoints before you commit a timeline. | procedure_lister · extension_finder · data_model_rebuilder · page_layout_tool | | New development | Build new features with zero hallucinations. Give your AI co-pilot accurate method signatures, real event publisher/subscriber graphs, dependency-aware suggestions, and field-level table analysis — all grounded in the actual codebase. | event_publisher_explorer · procedure_lister · table_field_analyzer · dependency_explorer | | System upgrades | Know exactly what breaks before you start. Compare source and target versions side by side and run consolidated upgrade reports combining event-subscription analysis, dependency checks, and SaaS-compatibility scans per object. | consolidated_upgrade_report · dependency_explorer · deprecated_code_explorer · saas_incompatibility_explorer · upgrade_tag_explorer |

See it role by role at www.veyomcp.com/your-team-upgraded.

Getting started

This setup mirrors the official documentation at docs.veyomcp.com/docs/mcp-configuration — always check there for the latest, full per-client guides.

Step 1 — Install Node.js

Veyo MCP runs through npx, which ships with Node.js. Install Node.js (LTS) on the machine where you'll run your AI client before going any further:

Windows — download the .msi installer from nodejs.org
macOS — download the .pkg installer, or brew install node
Linux — use your distro's package manager or the nodejs.org download page

Verify the install:

node -v
npx -v

Step 2 — Generate an API key

Generate an API key from the Veyo Cloud Portal. Every example below assumes you'll replace YOURAPIKEYHERE with that key.

Step 3 — Configure your AI client

Two scopes are available for most clients:

Project scope — the config lives in a project folder. Useful when you maintain multiple similar projects and want a different API key (and Veyo Project) per project.
User scope — the simplest option. Veyo tools become available automatically in any project you open. User scope always queries the same Veyo Project; switch it any time via the Default Project setting in your Veyo dashboard.

Pick your client below.

Add the server with the claude mcp add command.

Project scope (just this project):

claude mcp add veyo-mcp -s project -e VEYO_API_URL=https://portal.veyomcp.com -e VEYO_API_KEY=YOURAPIKEYHERE -- npx -y @darkloop/veyo-mcp@latest

User scope (all projects):

claude mcp add veyo-mcp -s user -e VEYO_API_URL=https://portal.veyomcp.com -e VEYO_API_KEY=YOURAPIKEYHERE -- npx -y @darkloop/veyo-mcp@latest

Cursor uses an mcp.json file with a top-level mcpServers key.

Project scope — create .cursor/mcp.json in your project root.
User scope — create ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json).

{
  "mcpServers": {
    "veyo-mcp": {
      "command": "npx",
      "args": ["-y", "@darkloop/veyo-mcp@latest"],
      "env": {
        "VEYO_API_URL": "https://portal.veyomcp.com",
        "VEYO_API_KEY": "YOURAPIKEYHERE"
      }
    }
  }
}

Verify: open Settings (Ctrl+Shift+J) → Features → Model Context Protocol and confirm veyo-mcp is listed and enabled, or run cursor-agent mcp list.

VS Code supports MCP through GitHub Copilot in Agent mode, using an mcp.json file with a top-level servers key.

Project scope — create .vscode/mcp.json in your project root:

{
  "servers": {
    "veyo-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@darkloop/veyo-mcp@latest"],
      "env": {
        "VEYO_API_URL": "https://portal.veyomcp.com",
        "VEYO_API_KEY": "YOURAPIKEYHERE"
      }
    }
  }
}

User scope — open the Command Palette (Ctrl/Cmd+Shift+P), run MCP: Open User Configuration, and paste the same JSON.

CLI alternative:

code --add-mcp '{"name":"veyo-mcp","command":"npx","args":["-y","@darkloop/veyo-mcp@latest"],"env":{"VEYO_API_URL":"https://portal.veyomcp.com","VEYO_API_KEY":"YOURAPIKEYHERE"}}'

Verify: run MCP: List Servers from the Command Palette.

Windsurf reads MCP configuration from a global mcp_config.json, making Veyo tools available across all projects.

Edit the file for your OS:

macOS/Linux — ~/.codeium/windsurf/mcp_config.json
Windows — %USERPROFILE%\.codeium\windsurf\mcp_config.json

(Or open it via the MCPs icon in Cascade, or Windsurf Settings → Cascade → MCP Servers → View raw config.)

{
  "mcpServers": {
    "veyo-mcp": {
      "command": "npx",
      "args": ["-y", "@darkloop/veyo-mcp@latest"],
      "env": {
        "VEYO_API_URL": "https://portal.veyomcp.com",
        "VEYO_API_KEY": "YOURAPIKEYHERE"
      }
    }
  }
}

After saving, restart Windsurf or click Refresh in the Manage MCPs panel. On Enterprise/team accounts an administrator may need to enable MCP access first.

Project scope — create .codex/config.toml in your project root (the project must be marked as trusted in Codex for this file to load):

[mcp_servers.veyo-mcp]
command = "npx"
args = ["-y", "@darkloop/veyo-mcp@latest"]

[mcp_servers.veyo-mcp.env]
VEYO_API_URL = "https://portal.veyomcp.com"
VEYO_API_KEY = "YOURAPIKEYHERE"

User scope — run this once to apply Veyo globally (updates ~/.codex/config.toml, or %USERPROFILE%\.codex\config.toml on Windows):

codex mcp add veyo-mcp --env VEYO_API_URL=https://portal.veyomcp.com --env VEYO_API_KEY=YOURAPIKEYHERE -- npx -y @darkloop/veyo-mcp@latest

Verify: run codex mcp list, or type /mcp during an interactive session.

Why npx? npx downloads and runs the latest version straight from npm — no manual install or updates needed. The -y flag auto-confirms. The package ships native binaries per platform, so the right one is fetched automatically.

Configuration reference

All configuration is passed through environment variables in your MCP client config:

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | VEYO_API_URL | Yes | The Veyo service URL. Use the cloud portal unless you've been given a dedicated instance. | https://portal.veyomcp.com | | VEYO_API_KEY | Yes | Your API key, generated in the Veyo Cloud Portal. | YOURAPIKEYHERE | | VEYO_PROJECT_ID | No | Pin queries to a specific Veyo Project. If omitted, the Default Project from your dashboard is used. | my-bc-project |

The same three values can also be passed as CLI flags after the package name: --api-url, --api-key, --project-id.

Available tools

Fourteen purpose-built tools. Your AI assistant discovers them automatically over MCP and picks the right one for each question.

Upgrade & compatibility analysis

consolidated_upgrade_report — the most powerful tool: combines event-subscription analysis, dependency checks, and SaaS-incompatibility scans into a single upgrade risk assessment for any object.
upgrade_tag_explorer — find ObsoleteState/ObsoleteReason tags for objects and fields, and the timeline for removal.
deprecated_code_explorer — surface deprecated patterns, obsolete API usage, and risky upgrade tags, with solution suggestions where available.
dependency_explorer — map external dependencies for an object and validate against a target version for breaking changes, including transitive analysis.
event_flow_tracker — trace the full execution chain from an event publisher through every custom and standard subscriber.
saas_incompatibility_explorer — identify code patterns incompatible with Business Central SaaS for cloud-migration planning.

Code analysis

event_publisher_explorer — list event publishers in an object by ID or wildcard pattern; discover integration points to subscribe to.
procedure_lister — browse all procedures in an object, or inspect one with its full body, variables, and parameters.
extension_finder — find TableExtensions, PageExtensions, EnumExtensions, and more that target a base object.
object_name_resolver — resolve object names to IDs and types with fuzzy matching.

Data & structure analysis

table_field_analyzer — deep-dive a table's field definitions: data types, properties, option strings, and validation rules.
data_model_rebuilder — analyse table relationships and traverse foreign-key chains, including extension impacts on the data model.

Page analysis

page_field_analyzer — analyse the fields on a page, or reverse-lookup which pages display a given table column.
page_layout_tool — retrieve the full hierarchical layout tree for a page (areas, groups, repeaters, controls) with their AL properties.

Every tool accepts a version_target parameter — "source" (your current version) or "target" (what you're upgrading to) — so your AI can compare across versions automatically.

Usage examples

Once configured, ask your AI assistant in plain language:

Upgrade analysis

"Run a comprehensive upgrade analysis for Codeunit 50099."
"What are the upgrade risks for Table 50075?"
"What event subscriptions will break after upgrade in Codeunit 50036?"

Code analysis

"Show me all dependencies for COD50099."
"What event publishers exist in Codeunit 80 that I can subscribe to?"
"List all procedures in the Sales-Post codeunit."

Data & page structure

"Analyse the Customer table structure."
"What fields are displayed on the Sales Order page?"
"Which pages show the 'Amount' field from the Sales Line table?"

Troubleshooting

MCP server won't start

Verify Node.js 18+ is installed: node --version.
Make sure your AI client picked up the config (reload/restart it after editing).

Tools return authentication or connection errors

Confirm your subscription is active and your API key is valid — generate or rotate it in the Veyo Cloud Portal.
Check VEYO_API_URL is set to https://portal.veyomcp.com (or your dedicated instance) and VEYO_API_KEY is correct.
If you're on a free trial that has expired, start a subscription at www.veyomcp.com.

No results for an object

Confirm the object exists in the Veyo Project you're querying, and that you're pointing at the right project (Default Project in the dashboard, or VEYO_PROJECT_ID).

Requirements

Node.js 18+ (for native fetch support)
An active Veyo subscription or free trial, with an API key from the Veyo Cloud Portal

Learn more

🌐 Website — www.veyomcp.com
📚 Documentation — docs.veyomcp.com
🔑 Portal & sign-up — portal.veyomcp.com
💬 Help & support — help.veyomcp.com