> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/integrations/ai-and-workflow/mcp.md).

# 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

```bash
npm i -g @helodata/mcp-server
```

Or run directly via `npx`:

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

## Configure in Claude Desktop

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

```json
{
  "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.