> ## Documentation Index
> Fetch the complete documentation index at: https://iotools.cloud/docs/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 800+ 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.

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

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

## What an agent sees

Five 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 five 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](/docs/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 '{ "ioPrompt": "a photorealistic cat on a sunny windowsill" }'
```

## Authentication today

Pass your API key as a Bearer token in the client config — see [Install](/docs/mcp/install).

<Note>
  OAuth is not available yet. Configure the key manually — it is the same key the REST API uses.
</Note>