# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.