Skip to main content

MCP Server Troubleshooting

Check Installation Status​

vai mcp status

This shows which AI tools have the vai MCP server configured.

Common Issues​

MCP server not detected by AI tool​

Symptoms: Claude Desktop/Cursor/VS Code doesn't show vai tools.

Solutions:

  1. Verify installation:

    vai mcp status

  2. Reinstall with force:

    vai mcp install claude --force

  3. Restart the AI tool — most tools only discover MCP servers on startup.

  4. Check the config file manually. For Claude Desktop:

    cat ~/.config/claude/claude_desktop_config.json

    Should contain a vai entry under mcpServers.

"VOYAGE_API_KEY not set" in MCP context​

The MCP server needs access to your Voyage AI API key. Ensure it's set in one of:

# Global config
vai config set api-key YOUR_KEY

# Or embed in MCP install
vai mcp install all --api-key YOUR_KEY

# Or environment variable
export VOYAGE_API_KEY=YOUR_KEY

MCP server crashes on startup​

Run manually with verbose logging to see errors:

vai mcp --verbose 2>mcp-errors.log

Common causes:

  • Missing API key
  • Node.js version too old (requires Node 18+)
  • Missing dependencies (npm install -g voyageai-cli to reinstall)

HTTP transport not connecting​

For HTTP transport mode:

# Start the server
vai mcp --transport http --port 3100

# Test it
curl http://localhost:3100/health

If using authentication, generate a key first:

vai mcp generate-key

Tools not working (empty results)​

If MCP tools connect but return empty results:

  1. Verify MongoDB is configured: vai config get mongodb-uri
  2. Verify the database/collection exists and has documents
  3. Set defaults: vai mcp --db myapp --collection docs

Resetting MCP Configuration​

# Remove from all tools
vai mcp uninstall all

# Reinstall fresh
vai mcp install all --force

Further Reading​