Troubleshooting

Having issues with the Rampify MCP server? This guide covers common problems and solutions.

Installation Errors#

Command not found#

Error:

bash: npx: command not found
bash: @rampify/mcp-server: command not found

Verify npm is installed:

npm --version

If this fails, install Node.js.

Try local installation:

npm install @rampify/mcp-server
npx @rampify/mcp-server

Check PATH (if globally installed):

npm config get prefix
# Add this to your PATH:
export PATH="$PATH:$(npm config get prefix)/bin"

Authentication Errors#

Authentication failed / Invalid API key#

Error:

Error: Authentication failed
Error: Invalid API key
Error: Unauthorized

Solution:

Verify API key format:

• Must start with sk_live_
• No quotes, spaces, or line breaks
• Copy the entire key from Settings > API Keys

Check environment variable name:

{
  "env": {
    "API_KEY": "sk_live_..."  // Correct ✅
  }
}

Verify key is active:

• Go to Settings > API Keys
• Check key hasn't been revoked
• Generate new key if needed

Test the key:

curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
    https://www.rampify.dev/api/sites

Should return your sites, not a 401 error.

Connection Errors#

Request timeout / Connection refused#

Error:

Error: Request timeout
Error: ETIMEDOUT
Error: Connection refused

Solution:

Check internet connection:

ping rampify.dev

Check firewall:

• Allow outbound HTTPS (port 443)
• Whitelist rampify.dev domain
• Check corporate proxy settings

Verify Rampify is accessible:

• Open https://www.rampify.dev in browser
• Should load without errors

Tools Not Appearing#

MCP tools don't show up in AI chat#

Symptoms:

• AI doesn't recognize Rampify commands
• Tools don't appear in tool list
• Editor shows no MCP connection

Solution:

Restart editor completely:

• Quit all windows (not just reload)
• Reopen editor

Verify config file location:

• Cursor: ~/.cursor/config.json
• Claude Code: ~/Library/Application Support/Claude/config.json (macOS)
• VS Code: ~/.vscode/mcp-settings.json
• Windsurf: ~/.codeium/windsurf/mcp_server_config.json
• Zed: ~/.config/zed/settings.json

Validate JSON syntax:

cat ~/.cursor/config.json | jq .

Fix any syntax errors (missing commas, brackets, quotes).

Check command path:

{
  "mcpServers": {
    "rampify": {
      "command": "npx",  // Must be exactly "npx"
      "args": ["-y", "@rampify/mcp-server"]
    }
  }
}

Check editor logs:

• Cursor: Help > Toggle Developer Tools > Console tab
• Look for errors mentioning rampify or mcp-server

Editor-Specific Issues#

Cursor#

Tools not appearing in Composer:

Update Cursor - Version 0.40+ required for MCP Check settings:

• Settings > Features > Enable MCP
• Restart after enabling

Tools require permission every time:

Add alwaysAllow to skip confirmations:

{
  "mcpServers": {
    "rampify": {
      "command": "npx",
      "args": ["-y", "@rampify/mcp-server"],
      "alwaysAllow": ["get_page_seo", "get_issues", "get_gsc_insights"],
      "env": {
        "API_KEY": "sk_live_...",
        "SEO_CLIENT_DOMAIN": "example.com"
      }
    }
  }
}

VS Code#

MCP tools not working:

1. Check VS Code version - June 2025+ for native MCP support
2. For older versions - Install Continue.dev extension
3. Reload window - Cmd+Shift+P > "Developer: Reload Window"

Windsurf#

Configuration not loading:

Ensure config file is in correct location:

• macOS/Linux: ~/.codeium/windsurf/mcp_server_config.json
• Windows: %APPDATA%\Codeium\windsurf\mcp_server_config.json

Zed#

Context servers not recognized:

Zed uses context_servers instead of mcpServers:

{
  "context_servers": {
    "rampify": {
      "command": "npx",
      "args": ["-y", "@rampify/mcp-server"],
      "env": {
        "API_KEY": "sk_live_...",
        "SEO_CLIENT_DOMAIN": "example.com"
      }
    }
  }
}