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

# MCP overview

> Every API-enabled IOTools.cloud tool, available to any MCP-capable agent

The [Model Context Protocol](https://modelcontextprotocol.io) lets an AI agent call external tools. IOTools.cloud makes **all 900+ API-enabled tools reachable over MCP**, so an agent can format JSON, convert a file or generate a QR code without a per-tool integration.

<Info>
  The MCP server is in **Beta**, same as the REST API — see [API overview](/api/overview).
</Info>

```
https://mcp.iotools.cloud/mcp
```

Streamable HTTP transport, OAuth or a Bearer API key, same credits and same tools as the REST API.

## What an agent sees

5 tools, not all. The catalog is reached through them:

| Tool            | What it does                                                     | Cost                 |
| --------------- | ---------------------------------------------------------------- | -------------------- |
| `search_tools`  | Find a tool by name, description or tag — ranked, with its price | Free                 |
| `describe_tool` | One tool's input schema, output schema and exact credit cost     | Free                 |
| `run_tool`      | Run any tool in the catalog by name                              | The tool's own price |
| `get_credits`   | What's left on your key                                          | Free                 |
| `get_usage`     | What you've spent it on, and what's left                         | Free                 |

Listing all supported tools with their schemas is a **\~844 KB, \~215k-token** `tools/list` — and most clients inject that on connect whether a tool gets used or not. The gateway is \~5.2 KB.

<Note>
  Listing is not permission: `tools/call` still resolves any tool by its own name. `run_tool` makes names *discoverable*, it doesn't gate them.
</Note>

## The full listing

If your client loads tools **lazily** (Claude Code, the Claude API's tool-search), it pays no context for tools it doesn't touch and typed schemas beat a generic `run_tool`. Ask for the catalog on the connect URL:

```
https://mcp.iotools.cloud/mcp?listing=full
```

Every tool then appears by name with its own `inputSchema` and `outputSchema` — the same ones `describe_tool` and the OpenAPI document give. Names are the slug, `/` replaced by `__` (MCP names can't contain slashes): `case-converter`, `html-generator__button`. The 5 tools above are still there.

Don't use it on a client that loads eagerly — that's the 215k-token bill, mostly wasted.

## Cost

Same meter as REST: **every `tools/call` on a real tool costs credits**, refunded if the call fails. `run_tool` costs exactly what the inner tool costs. See [Credits](/concepts/credits).

<Warning>
  One user request often becomes 15–25 tool calls, so an agent burns credits faster than hand-written code. Watch [your account](https://iotools.cloud/account/) for the first few sessions.
</Warning>

## Your agent can't spend credits without asking

Nothing about a tool-calling loop naturally stops at your allowance — so **every paid call is put up for approval before anything is charged.** Every one, not just the first: there is no "remember this" and no per-session allowance.

Clients that implement [MCP elicitation](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation) surface that as a prompt, quoting the price:

> String Case Converter costs 3 credits. Run it?

<Note>
  The server always asks; **how your client presents the question is the client's choice.** One that auto-approves without showing you anything is still behaving within the protocol. If it matters to you, check how yours handles elicitation — we can guarantee the ask, not that a human sees it.
</Note>

| You            | What happens                                                                   |
| -------------- | ------------------------------------------------------------------------------ |
| **Accept**     | Runs, and charges at most the quoted price — never more                        |
| **Decline**    | Nothing runs, nothing is charged. The agent is told to ask you before retrying |
| **Dismiss it** | Counts as a decline                                                            |

The prompt lands **after** your inputs are validated and **before** any credit moves — the only window where "no" is free. Through `run_tool` it quotes the inner tool's price, so the gateway is no way around it.

The quoted number is what gets charged; it can only end up **lower**, never higher. Failed runs are refunded in full, and per-unit tools that under-deliver refund the shortfall.

Free tools never interrupt you, so an agent can search, read a schema and check your balance without asking — then ask once, for the call that spends something.

### If your client can't show a prompt

Those clients keep working — each tool's price is in its description anyway.

<Warning>
  One exception: without a prompt, a single call over **50 credits** is refused rather than spent silently. Today that's only `ai-image-generator` at 640 credits, most of a free month's allowance in one call.
</Warning>

To run a blocked tool, call REST directly with the same key — you're the one pressing enter:

```bash theme={"system"}
curl -X POST https://api.iotools.cloud/v1/tool/ai-image-generator \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "a photorealistic cat on a sunny windowsill" }'
```

## Authentication

Two ways in, and both meter identically — same credits, same tier, same rate limit:

* **OAuth** — for clients that support it (Claude.ai, Claude Desktop's Connectors settings). The connector signs in and authorizes itself; there's no key to copy or paste. Consent shows the requesting app's name and is asked every time a grant is issued, not skipped after the first.
* **API key** — pass it as a Bearer token in the client config, for clients that only take a static config file (Cursor, Windsurf, most others).

See [Install](/mcp/install) for both, step by step.

<Note>
  Authorized an app with OAuth? [Account → Connected apps](https://iotools.cloud/account/#connected-apps) lists every live grant and revokes one immediately — no waiting on a token to expire.
</Note>