> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotools.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Install

> Add IOTools.cloud to Claude, Cursor, Windsurf or any MCP client

Two ways to connect, depending on your client — both use the same credits, tier and rate limit.

* **[OAuth](#oauth)** — for clients that support it (Claude.ai, Claude Desktop's Connectors settings). No key to copy: sign in and authorize from a screen on iotools.cloud, revoke anytime from your account.
* **[API key](#api-key)** — for clients that only take a static config file (Cursor, Windsurf, most others). Paste a Bearer key once.

## OAuth

<Steps>
  <Step title="Add the connector">
    **Claude.ai** — Settings → Connectors → Add custom connector.
    **Claude Desktop** — Settings → Connectors → Add custom connector.

    Enter the server URL:

    ```
    https://mcp.iotools.cloud/mcp
    ```
  </Step>

  <Step title="Sign in and authorize">
    Claude opens iotools.cloud in a browser. Sign in (or create a free account if you don't have one), then approve the connection on the consent screen — it names the app asking and what it's requesting, every time, not just the first.
  </Step>

  <Step title="Done">
    Claude reconnects on its own after this — no key, no config file, nothing to keep in sync.
  </Step>
</Steps>

<Note>
  Revoke access anytime from [Account → Connected apps](https://iotools.cloud/account/#connected-apps). It's immediate — the app's access stops on its very next call, not after some token expires.
</Note>

## API key

Every client below reads the same shape. Get a key from [Account → API keys](https://iotools.cloud/account/#api-keys), then substitute it:

```json theme={"system"}
{
  "mcpServers": {
    "iotools": {
      "type": "http",
      "url": "https://mcp.iotools.cloud/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

<Tabs>
  <Tab title="Claude Desktop">
    Prefer OAuth above if your version supports Connectors — it's simpler and needs no file editing. To configure a key manually instead (e.g. for a version that predates Connectors), edit `claude_desktop_config.json`:

    * **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`
    * **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`

    Add the block above, then **fully quit and reopen Claude** — reloading the window is not enough.
  </Tab>

  <Tab title="Cursor">
    **Settings → MCP → Add new global MCP server**, or edit `~/.cursor/mcp.json` directly with the block above.
  </Tab>

  <Tab title="Windsurf">
    **Settings → Cascade → MCP servers → Add server**, then paste the block.
  </Tab>

  <Tab title="Other clients">
    Any client supporting the **Streamable HTTP** transport works. Point it at `https://mcp.iotools.cloud/mcp` and send `Authorization: Bearer YOUR_API_KEY`.
  </Tab>
</Tabs>

<Warning>
  This config file holds a live credential in plaintext. Don't commit it, and don't paste it into a chat — including into the agent you are configuring.
</Warning>

## Listing all 900+ tools

A session advertises 5 tools by default; the catalog is reached through `search_tools` → `describe_tool` → `run_tool`, because the full listing is \~215k tokens and most clients load it eagerly. If yours loads tools **lazily** (Claude Code, the Claude API's tool-search), add `?listing=full` for every tool by name with its own schema:

```json theme={"system"}
"url": "https://mcp.iotools.cloud/mcp?listing=full"
```

Works with either auth method — append it to the connector URL for OAuth, or to `url` in the config above. Same key or grant, same credits, same tools. See [the overview](/mcp/overview#the-full-listing).

## Check it worked

Ask the agent something only a tool can answer:

> Use IOTools to convert "hello world" to uppercase.

It should find `case-converter` with `search_tools` and run it with `run_tool`, coming back with `HELLO WORLD`. If it answers without calling a tool, it hasn't loaded the server — restart the client.

Clients that support elicitation stop and ask before the paid call:

> String Case Converter costs 3 credits. Run it?

That's the safeguard, not a glitch — approve and it runs, decline and nothing is charged. See [Your agent can't spend credits without asking](/mcp/overview#your-agent-cant-spend-credits-without-asking).

If you connected via OAuth, the app also shows up under [Account → Connected apps](https://iotools.cloud/account/#connected-apps) — a quick way to confirm the grant actually went through.

## Troubleshooting

| Symptom                                                      | Cause                                                                                                                                                 |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| No IOTools tools listed                                      | Client not restarted, or malformed JSON (API key method). A trailing comma is the usual culprit                                                       |
| Only 5 tools listed                                          | That's the default — the catalog is behind `search_tools`/`run_tool`. Add `?listing=full` if your client loads tools lazily                           |
| "Couldn't register" or similar, adding the connector (OAuth) | Transient — retry. If it persists, fall back to the API key method while it's investigated                                                            |
| Every call fails with `invalid_api_key`                      | Key revoked, or `Bearer ` prefix missing (API key method)                                                                                             |
| Agent says it lost access partway through a session          | Someone disconnected the app from [Account → Connected apps](https://iotools.cloud/account/#connected-apps) (OAuth), or the key was revoked (API key) |
| `insufficient_credits`                                       | Out of credits for the month — see [Credits](/concepts/credits)                                                                                       |
| `tool_not_found`                                             | The agent invented a tool name. Tell it to run `search_tools` first                                                                                   |
| `validation_error` on a field name                           | The agent guessed the inputs. Tell it to call `describe_tool` before `run_tool`                                                                       |