Troubleshoot Vega DevTools MCP

This page helps you resolve common issues when setting up and using Vega DevTools MCP with your AI agent. Each issue includes the problem description, likely causes, and step-by-step solutions.

If you haven't set up Vega DevTools MCP yet, see Set Up Vega DevTools MCP Server.

Common issues

AI agent doesn’t use Vega DevTools MCP to answer Vega-related questions

Cause: The MCP server installation or configuration has an issue, or the AI agent requires a restart after configuration.

Solution:

1. Verify MCP server installation:

   Copy code Copied to clipboard.

   npx @amazon-devices/vega-devtools-mcp@latest --help
   

2. Check MCP configuration in your AI agent's settings file.
3. Restart your AI agent after configuration changes.

Error message says document isn’t included in vega-devtools-mcp version

Cause: The document name contains a typo, the document doesn't exist, or you have an outdated version of the MCP server.

Solution:

1. List available documents:

   Copy code Copied to clipboard.

   Show me all the documents in Vega DevTools MCP
   

2. Verify the availability of the document name and the spelling is accurate.
3. Update to latest MCP server version if needed.

AI agent provides generic responses not Vega-specific guidance

Cause: Context initialization didn’t complete, context files are missing, or AI agent isn’t recognizing the context files.

Solution:

1. Verify context initialization is complete:

   Copy code Copied to clipboard.

   npx @amazon-devices/vega-devtools-mcp@latest --init-context
   

2. Check that context files exist in your project root:

   Copy code Copied to clipboard.

   ls AGENTS.md
   

   If the file doesn't exist: Use the prompt-based alternative instead. In your AI agent prompt, enter:

   Copy code Copied to clipboard.

   use vega-devtools-mcp for context
   

3. Restart AI agent session and verify context recognition:

   3.1 To restart an AI agent, close your current chat conversation and start a new on. 3.2 In the prompt, enter:

   Copy code Copied to clipboard.

   use AGENTS.md for context
   

   3.3 Ask a Vega-specific question to confirm the agent provides relevant guidance. For example:

   Copy code Copied to clipboard.

   Can you list all documents related to feature development on vega?
   

vega-devtools-mcp fails to load

After adding the config, IDE fails to initialize the MCP and displays:

MCP error -32000: Connection closed  

Cause: The following issues can cause this:

• Installation failed
• Node version mismatch

Solution:

If installation fails:

Verify the installation works without MCP:

Run npx @amazon-devices/vega-devtools-mcp@latest --help  

If you still encounter the same issue, run:

npm install -g @amazon-devices/vega-devtools-mcp@latest

If Node version mismatches:

Each node version maintains its own copy of “global” installations. To verify that @amazon-devices/vega-devtools-mcp@latest appears for your current Node version, run:

npm list -g 

For example, nvm use 20 && npm list -g have its own list as compared to nvm use 22 && npm list -g, depending on which Node you used during installation.

vega-devtools-mcp doesn’t work with asdf

Cause: asdf is a version manager for installing Node.js. asdf handles Node.js differently from other node managers like nvm. vega-devtools-mcp expects a node binary, but asdf creates a shell script, which causes initialization issue for vega-devtools-mcp.

When you use asdf, this configuration may work on CLI but can cause IDE issues (MCP error -32000: Connection closed)

    "vega-devtools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@amazon-devices/vega-devtools-mcp@latest"
      ]
    },

Solution:

1. Install the MCP:

   Copy code Copied to clipboard.

   npm install -g @amazon-devices/vega-devtools-mcp@latest
   

2. Obtain path of node binary:

   Copy code Copied to clipboard.

   % asdf which node
   

   You see an output similar to this (it differs based on your ASDF_DATA_DIR setting):

   ~/ASDF_DATA/installs/nodejs/22.20.0/bin/node
   

3. Obtain path of vega-devtools-mcp binary:

   Copy code Copied to clipboard.

   % asdf which vega-devtools-mcp
   

   You see an output similar to this (it differs based on your ASDF_DATA_DIR setting):

   <>/ASDF_DATA/installs/nodejs/22.20.0/bin/vega-devtools-mcp
   

4. Update your config using these paths (replace the paths with your actual output and remove comments after updating):

   Copy code Copied to clipboard.

   "vega-devtools-mcp-npx": {
       "type": "stdio",
       "command": "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/node", // path copied from above
       "args": [
           "<>/ASDF_DATA/installs/nodejs/22.20.0/bin/vega-devtools-mcp" // path copied from above
      ]
   },
   

   Related topics

• Set Up Vega DevTools MCP Server

Last updated: Dec 22, 2025