Skip to main content

FAQ: MCP

Common questions about integrating, configuring, and using the Aluvia MCP Server.

What is the Aluvia MCP Server?

The Aluvia MCP Server is a remote Model Context Protocol (MCP) service that allows AI assistants, IDEs, and automation tools to securely manage your Aluvia connectivity credentials.

Through MCP, clients like Claude, VS Code (GitHub Copilot), Cursor, Amp, and others can:

  • List existing connectivity credentials in your Aluvia account
  • Create new credentials on demand
  • Update credential settings (e.g., sticky sessions)
  • Test connectivity via real HTTP requests
  • Fetch account usage statistics for monitoring and analytics

All operations are performed over a secure, authenticated API at:

https://mcp.aluvia.io
Where do I get my Aluvia Token?

You can find your Aluvia Token in the Dashboard:

  1. Sign in to your Aluvia account
  2. Go to the Credentials page
  3. Copy your token

This token is used for connecting to the MCP server:

Authorization: Bearer YOUR_ALUVIA_TOKEN
How do I connect my MCP client to Aluvia?

Most MCP-compatible clients use a similar configuration.

Example:

{
  "mcpServers": {
    "Aluvia": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.aluvia.io",
        "--header",
        "Authorization: Bearer YOUR_ALUVIA_TOKEN"
      ]
    }
  }
}

Replace YOUR_ALUVIA_TOKEN with your token from the Aluvia Dashboard. Many tools (VS Code, Warp, Cursor, Qodo Gen, Windsurf, etc.) provide a UI where you can paste or import this configuration.

Which AI tools and IDEs work with the Aluvia MCP Server?

Any client that supports the Model Context Protocol (MCP) or the mcp-remote interface can connect.

Common examples include:

  • Claude Desktop / Claude Code
  • VS Code (GitHub Copilot Agents)
  • Cursor
  • Amp
  • Warp
  • Windsurf
  • LM Studio
  • Qodo Gen
  • Custom agents or backends using npx mcp-remote https://mcp.aluvia.io

All of them use the same endpoint and authorization header.

How do I test whether a credential works?

Use the test_proxy_credential MCP tool.

You provide the username of the credential and optionally a custom URL to test against (default: https://ipconfig.io/json).

Example JSON-RPC call:

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "test_proxy_credential",
    "arguments": {
      "username": "username123",
      "url": "https://ipconfig.io/json"
    }
  }
}

The response includes status code, response body, and detailed connectivity information.

Why am I getting a “spawn npx ENOENT” or similar error?

This occurs when your system or MCP client cannot find the npx executable.

To fix it:

  1. Verify Node.js is installed

    • macOS: which node
    • Windows: where node

  2. Update your MCP configuration to use the Node.js binary directly rather than npx.

Example:

{
  "mcpServers": {
    "Aluvia": {
      "command": "/usr/local/bin/node",
      "args": [
        "node_modules/mcp-remote/cli.js",
        "https://mcp.aluvia.io",
        "--header",
        "Authorization: Bearer ALUVIA_TOKEN"
      ]
    }
  }
}

Adjust paths based on your environment.