Skip to main content

Aluvia MCP Server

Easily manage your Aluvia proxy credentials directly from AI assistants or any client that supports the Model Context Protocol (MCP).

This MCP server exposes a secure, authenticated API at https://mcp.aluvia.io, giving you programmatic access to manage proxies in real time.

Quick Start with MCP Client​

The Aluvia MCP Server works with any MCP client. Use the standard configuration below and substitute your API key.

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

Replace ALUVIA_API_KEY with your personal API key from your Aluvia dashboard.

Authorization​

All requests to the MCP server require your Aluvia API Key.

Include it in the HTTP header as:

Authorization: Bearer <ALUVIA_API_KEY>

You can find your API key from your Aluvia account's Dev Tools page.

Available Tools​

Below are the tools exposed by the Aluvia MCP Server. Each tool can be invoked using the tools/call method in a JSON-RPC request.

list_proxy_credentials​

List all proxy credentials in your Aluvia account.

  • Inputs

    • None

  • Response

    • content (object) — A text block containing all available proxy credentials in JSON format.

create_proxy_credential​

Create one or more new proxy credentials.

  • Inputs

    • count (number) — Number of credentials to create. Default: 1.

  • Response

    • content (object) — Details of the created proxy credentials in JSON format.

update_proxy_credential​

Update proxy settings such as sticky sessions or smart routing.

  • Inputs

    • username (string) — Username of the proxy credential to update.
    • useSticky (boolean, optional) — Enable or disable sticky sessions.
    • useSmartRouting (boolean, optional) — Enable or disable smart routing.

  • Response

    • content (object) — The updated proxy credential with the new configuration options.

delete_proxy_credential​

Permanently delete a proxy credential.

  • Inputs

    • username (string) — Username of the proxy credential to delete.

  • Response

    • content (string) — Confirmation message that the credential has been deleted.

test_proxy_credential​

Test a proxy by making an HTTP request through it.

  • Inputs

    • username (string) — Username of the proxy credential to test.
    • url (string, optional) — The URL to test against. Default: http://lumtest.com/myip.json.

  • Response

    • content (object) — Response data including HTTP status, body, and connection success or error details.

get_proxy_credential_usage​

Retrieve usage statistics for a proxy credential over a given time window.

  • Inputs

    • username (string) — Username of the proxy credential.
    • usageStart (number, optional) — Start time (Unix timestamp). Defaults to 24 hours ago.
    • usageEnd (number, optional) — End time (Unix timestamp). Defaults to now.

  • Response

    • content (object) — Raw usage statistics in JSON format.

Example Requests​

Replace ALUVIA_API_KEY and any usernames with your actual credentials.

List Tools

curl -s https://mcp.aluvia.io/ \
  -H 'Authorization: Bearer ALUVIA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

List Proxy Credentials

curl -s https://mcp.aluvia.io/ \
  -H 'Authorization: Bearer ALUVIA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":"2",
    "method":"tools/call",
    "params":{
      "name":"list_proxy_credentials",
      "arguments":{}
    }
  }'

Test Proxy Credential

curl -s https://mcp.aluvia.io/ \
  -H 'Authorization: Bearer ALUVIA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0",
    "id":"3",
    "method":"tools/call",
    "params":{
      "name":"test_proxy_credential",
      "arguments":{
        "username":"your_proxy_username",
        "url":"http://lumtest.com/myip.json"
      }
    }
  }'

Using with Other MCP Clients​

Standard config works in most of the tools:

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

Add via the Amp VS Code extension settings screen or by updating your settings.json file:

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

Amp CLI Setup:

Add via the amp mcp addcommand below

amp mcp add Aluvia -- npx -y mcp-remote https://mcp.aluvia.io --header "Authorization: Bearer ALUVIA_API_KEY"
Claude Code

Use the Claude Code CLI to add the Aluvia MCP server:

claude mcp add Aluvia npx -y mcp-remote https://mcp.aluvia.io --header "Authorization: Bearer ALUVIA_API_KEY"
Claude Desktop

Follow the MCP install guide, use the standard config above.

Codex

Create or edit the configuration file ~/.codex/config.toml and add:

[mcp_servers.Aluvia]
command = "npx"
args = ["-y","mcp-remote","https://mcp.aluvia.io","--header","Authorization: Bearer ALUVIA_API_KEY"]

For more information, see the Codex MCP documentation.

Cursor

Go to Cursor Settings -> MCP -> Add new MCP Server. Name to your liking, use command type with the command npx -y mcp-remote https://mcp.aluvia.io --header "Authorization: Bearer ALUVIA_API_KEY". You can also verify config or add command like arguments via clicking Edit.

Gemini CLI

Follow the MCP install guide, use the standard config above.

Goose

Go to Advanced settings -> Extensions -> Add custom extension. Name to your liking, use type Streamable HTTP, and set the command to npx -y mcp-remote https://mcp.aluvia.io --header "Authorization: Bearer ALUVIA_API_KEY". Click "Add Extension".

Kiro

Follow the MCP Servers documentation. For example in .kiro/settings/mcp.json:

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

Go to Program in the right sidebar -> Install -> Edit mcp.json. Use the standard config above.

opencode

Follow the MCP Servers documentation. For example in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Aluvia": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "mcp-remote",
        "https://mcp.aluvia.io",
        "--header",
        "Authorization: Bearer ALUVIA_API_KEY"
      ],
      "enabled": true
    }
  }
}
Qodo Gen

Open Qodo Gen chat panel in VSCode or IntelliJ → Connect more tools → + Add new MCP → Paste the standard config above.

Click Save.

VS Code

Follow the MCP install guide, use the standard config above. You can also install the Aluvia MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"Aluvia","command":"npx","args":["-y","mcp-remote","https://mcp.aluvia.io","--header","Authorization: Bearer ALUVIA_API_KEY"]}'

After installation, the Aluvia MCP server will be available for use with your GitHub Copilot agent in VS Code.

Warp

Go to Settings -> AI -> Manage MCP Servers -> + Add to add an MCP Server. Use the standard config above.

Alternatively, use the slash command /add-mcp in the Warp prompt and paste the standard config from above:

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

Follow Windsurf MCP documentation. Use the standard config above.

What is MCP?​

Model Context Protocol (MCP) is an open standard that defines how large language models (LLMs) and developer tools communicate.

It provides a consistent interface that allows AI systems — like Claude, ChatGPT, or custom assistants — to connect to external services in a structured and secure way.

Instead of hardcoding integrations or relying on one-off plugins, MCP enables a unified method for:

  • Exposing tools and APIs to AI models
  • Sending and receiving structured JSON messages
  • Managing authentication and streaming results
  • Allowing any client or IDE to use the same server logic

In simple terms, MCP turns APIs into "tools" that AI models can call, letting them access real-world data and actions (like fetching proxies, running a browser, or querying a database) through a single consistent interface.

Learn More​

If you're new to MCP, here are official resources to get started:

These resources explain how MCP works, how to build your own MCP servers, and how to connect them to clients like Claude, VS Code, or other AI-driven environments.