Vela.MCP - Model Context Protocol Server for NAV/Business Central

Vela.MCP is an MCP (Model Context Protocol) server that provides Business Central/NAV codebase analysis tools directly to Claude Desktop and Claude Code. It connects to a Vela API server which manages the Qdrant vector database containing pre-ingested code analysis data.

Quick Start

Claude Desktop

Add this configuration to your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS/Linux: ~/.config/Claude/claude_desktop_config.json

For macOS/Linux:

{
  "mcpServers": {
    "vela": {
      "command": "npx",
      "args": ["-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "vela": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

Then reload MCP configuration in Claude Desktop.

Claude Code

Add the MCP server using the mcp add command:

claude mcp add vela-mcp npx vela-mcp --scope user

Then configure the environment variables in your project's .claude/mcp.json or globally in ~/.claude/mcp.json:

For macOS/Linux:

{
  "mcpServers": {
    "vela-mcp": {
      "command": "npx",
      "args": ["-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "vela-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

Cursor

Add this configuration to your Cursor MCP settings file (usually ~/.cursor/mcp.json or in your project settings):

For macOS/Linux:

{
  "mcpServers": {
    "vela": {
      "command": "npx",
      "args": ["-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

For Windows:

{
  "mcpServers": {
    "vela": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "vela-mcp"],
      "env": {
        "VELA_API_URL": "http://192.168.0.2:8000",
        "VELA_API_KEY": "your-api-key-here",
        "VELA_PROJECT_ID": "your-project-id-here"
      }
    }
  }
}

Then restart Cursor to load the MCP server.

How it works:

• npx automatically downloads and runs the latest version from NPM
• -y flag auto-confirms the installation
• No manual installation or updates needed!

Note for Windows users: Windows requires the cmd /c wrapper because npx is a batch file (.cmd) that cannot be executed directly. The cmd /c command tells Windows to run the batch file through the command interpreter.

Configuration

Environment Variables

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

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | VELA_API_URL | Yes | The URL of your Vela API server | http://192.168.0.1:8000 | VELA_API_KEY| Yes | Your API authentication key |your-api-key-here| |VELA_PROJECT_ID| Yes | Project identifier (sent asX-Project-IDheader) |my-bc-project` |

Available Tools

The MCP server exposes Business Central/NAV analysis tools:

Upgrade & Compatibility Analysis

• consolidated_upgrade_report: Comprehensive upgrade analysis combining deprecated patterns, events, and dependencies
• upgrade_tag_explorer: Find upgrade/obsolete tags for objects and fields
• deprecated_code_explorer: Identify deprecated patterns and risky upgrade tags
• dependency_explorer: Analyze dependencies and validate against target version for breaking changes
• event_flow_tracker: Track event publisher-subscriber chains and identify breaking subscriptions
• saas_incompatibility_explorer: Find SaaS-incompatible code patterns

Code Analysis

• ask: Ask natural language questions about the codebase with AI-powered search
• event_publisher_explorer: Find event publishers in objects by ID or wildcard pattern
• procedure_lister: List all procedures in an object with signatures
• extension_finder: Find table/page extensions for base objects
• object_name_resolver: Resolve object names to IDs with fuzzy matching

Data & Structure Analysis

• table_field_analyzer: Analyze table structures with complete field definitions
• data_model_rebuilder: Rebuild data models and analyze table relationships

Usage Examples

Once configured, you can ask Claude:

Upgrade Analysis

• "Run a comprehensive upgrade analysis for Codeunit 50099"
• "What are the upgrade risks for Table 50075?"
• "Find upgrade tags for Table 36 field Amount"
• "What event subscriptions will break after upgrade in Codeunit 50036?"

Code Analysis

• "Show me all dependencies for COD50099"
• "Find deprecated code patterns in the source version"
• "What event publishers exist in Codeunit 80?"
• "List all procedures in Codeunit 50099"

Data Structure Analysis

• "Analyze the Customer table structure"
• "Show me complete field definitions for Table 50075"

Development

Build from Source

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run locally
node dist/index.js

Project Structure

Vela.MCP/
├── src/
│   └── index.ts              # TypeScript MCP server implementation
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # NPM configuration
├── tsconfig.json            # TypeScript compiler configuration
└── README.md                # This file

Troubleshooting

Common Issues

MCP server won't start:

• Verify Node.js 18+ is installed: node --version
• Check the API server is running at the configured URL
• Review Claude Desktop logs for connection errors

Tools returning errors:

• Verify VELA_API_URL is correct and accessible
• Check VELA_API_KEY is valid
• Ensure the Vela API server is running and connected to Qdrant

Can't connect to API:

• Test the API directly: curl http://192.168.0.178:8342/docs
• Check firewall settings if API server is on different machine
• Verify the API server is listening on the correct port

Manual Testing with CLI Arguments

For testing without Claude Desktop, use CLI arguments:

node dist/index.js --api-url http://192.168.0.178:8342 --api-key your-key --project-id your-project

Requirements

• Node.js 18+ (for native fetch support)
• Running Vela API server
• Qdrant database with ingested BC/NAV codebase data (managed by API server)

License

[Your License Here]