> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.helodata.com/integrations/ai-and-workflow/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.