> For the complete documentation index, see [llms.txt](https://docs.ipdunar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipdunar.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. ipdunar ships an MCP server that exposes proxied fetch + ISP/session management as tools an agent can use directly.

## What the server exposes

| Tool                     | Description                                                                             |
| ------------------------ | --------------------------------------------------------------------------------------- |
| `ipdunar_fetch`          | Fetch a URL through ipdunar; choose product (`res`/`mob`/`isp`), region, sticky session |
| `ipdunar_list_locations` | Return available regions/cities/ASNs for `res` and `mob`                                |
| `ipdunar_isp_list`       | Return your purchased ISP IPs                                                           |
| `ipdunar_traffic_today`  | Today's bandwidth usage by product and sub-user                                         |

## Install

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

Or run directly via `npx`:

```bash
npx -y @ipdunar/mcp-server --api-key=YOUR_IPDUNAR_API_KEY
```

## Configure in Claude Desktop

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

```json
{
  "mcpServers": {
    "ipdunar": {
      "command": "npx",
      "args": ["-y", "@ipdunar/mcp-server"],
      "env": {
        "IPDUNAR_API_KEY":      "YOUR_API_KEY",
        "IPDUNAR_SUBUSER":      "s1a2b3c4d5e",
        "IPDUNAR_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 `ipdunar_fetch` tool to get the homepage of `https://example.de` from a German residential IP, and summarize the meta description."

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

## Sticky sessions in MCP

`ipdunar_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+).
* **`ipdunar_fetch` returns 407** — the env var creds in the config are wrong; verify in the dashboard.
* **Large responses** — `ipdunar_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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
