MCP server

The Model Context Protocol (MCP) lets LLM-driven agents (Claude Desktop, Cursor, Cline, others) call external tools. helodata ships an MCP server that exposes proxied fetch + ISP/session management as tools an agent can use directly.

What the server exposes

Tool	Description
helo_fetch	Fetch a URL through helodata; choose product (res/mob/isp), region, sticky session
helo_list_locations	Return available regions/cities/ASNs for res and mob
helo_isp_list	Return your purchased ISP IPs
helo_traffic_today	Today's bandwidth usage by product and sub-user

Install

npm i -g @helodata/mcp-server

Or run directly via npx:

npx -y @helodata/mcp-server --api-key=YOUR_HELODATA_API_KEY

Configure in Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "helodata": {
      "command": "npx",
      "args": ["-y", "@helodata/mcp-server"],
      "env": {
        "HELODATA_API_KEY":      "YOUR_API_KEY",
        "HELODATA_SUBUSER":      "s1a2b3c4d5e",
        "HELODATA_SUBUSER_PASS": "PASSWORD"
      }
    }
  }
}

Restart Claude Desktop. The new tools appear in the tool list when prompted.

Configure in Cursor / Cline

Same JSON shape under mcp (Cursor) or mcp_servers (Cline). See each tool's MCP docs for the exact field name.

Example agent prompt

"Use the helo_fetch tool to get the homepage of https://example.de from a German residential IP, and summarize the meta description."

The agent picks helo_fetch with region=de, type=res, gets the page, parses, summarizes.

Sticky sessions in MCP

helo_fetch accepts a session_id parameter. Pass the same value across multiple tool calls in one conversation to reuse the same exit IP — useful for multi-step flows.

Security note

The MCP server uses your API key to bill and authenticate. Treat it like a database password. Scope the API key to read-only operations if your agent doesn't need to manage orders / sub-users.

Common pitfalls

• MCP server not appearing — check Claude Desktop logs at ~/Library/Logs/Claude/mcp.log (macOS) or equivalent. Most often it's a Node version mismatch (require Node 18+).
• helo_fetch returns 407 — the env var creds in the config are wrong; verify in the dashboard.
• Large responses — helo_fetch truncates above 1 MB by default; raise via the max_bytes parameter when the agent asks for full HTML.