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

# Agent Cloud

> Empower your AI agents to provision, manage, and scale GPU infrastructure via the io.net network.

## What is Agent Cloud?

The **Agent Cloud is a Model Context Protocol (MCP)** server which allows any MCP-compatible AI agent (Claude Code, Cursor, Windsurf, etc.) to interact directly with [**<u>io.net</u>**](http://io.net) APIs. Instead of manual dashboard management, you can now manage your decentralized infrastructure through natural language.

## Why Connect to Agent Cloud?

* **Agentic DevOps:** Ask your agent to "Find the cheapest 4x H100 cluster and deploy my PyTorch image," and let it handle the API calls.
* **Plug-and-Play:** No custom SDKs to install. Use the universal MCP standard to bridge your AI tools to the large GPU cloud.
* **Enterprise Ready:** Supports both simple API key headers for individuals and dynamic key forwarding for multi-tenant applications.
* **x402 Payments:** When credits run short, a deploy returns an x402 payment request your agent can settle in USDC and retry, with no trip back to the dashboard.

## Quickstart: Connect to the IO Cloud

You can link your AI agent to our hosted MCP server in seconds.

### 1. Link Your Agent (Claude Code Example)

Replace `<YOUR_IO_NET_API_KEY>` with your personal key from the io.net dashboard with `io-cloud` project scopes:

```shellscript theme={null}
claude mcp add io-cloud https://mcp.io.solutions/mcp \
  --transport http \
  --header "x-api-key: <YOUR_IO_NET_API_KEY>" \
  --scope project
```

### 2. Verify Connection

Once added, restart your agent and try these prompts:

* *"What io-cloud tools are available to me?"*
* *"List all active container deployments in my account."*
* *"Find available NVIDIA H100 hardware specs."*

## Desktop Agent Configuration

If you prefer using GUI-based agents, copy and paste the configurations below. Replace `<YOUR_IO_NET_API_KEY>` with your actual key with `io-cloud` project scopes.

### Claude Desktop

Add this to your `claude_desktop_config.json` (found in `%AppData%\Claude` on Windows or `~/Library/Application Support/Claude` on macOS):

```javascript theme={null}
{
  "mcpServers": {
    "io-cloud": {
      "type": "http",
      "url": "https://mcp.io.solutions/mcp",
      "headers": {
        "x-api-key": "<YOUR_IO_NET_API_KEY>"
      }
    }
  }
}
```

### Cursor & Windsurf

1. Open **Settings** > **Features** > **MCP**.
2. Click **+ Add New MCP Server**.
3. **Name:** `io-cloud`
4. **Type:** `command` (or `http` if supported).
5. **URL:** `https://mcp.io.solutions/mcp`
6. **Header:** `x-api-key: <YOUR_IO_NET_API_KEY>`

## Capabilities & Documentation

### Available MCP Tools

| **Tool Group** | **Capability**                    | **Purpose**                                        |
| :------------- | :-------------------------------- | :------------------------------------------------- |
| **CaaS**       | `caas_get_hardware_ids`           | Browse the deployable container hardware catalog.  |
| **CaaS**       | `caas_get_max_gpus_per_container` | Max GPU count allowed in a single container.       |
| **CaaS**       | `caas_get_available_replicas`     | Replicas available for a hardware ID and quantity. |
| **CaaS**       | `caas_get_price_estimate`         | Cost of a configuration before you deploy it.      |
| **CaaS**       | `caas_deploy_container`           | Instant provisioning of new compute resources.     |
| **CaaS**       | `caas_list_deployments`           | Real-time status of your container clusters.       |
| **CaaS**       | `caas_get_deployment`             | Details of a single deployment.                    |
| **CaaS**       | `caas_get_deployment_containers`  | Containers running inside a deployment.            |
| **CaaS**       | `caas_update_deployment`          | Change an existing deployment.                     |
| **CaaS**       | `caas_extend_deployment_duration` | Add runtime to a deployment.                       |
| **CaaS**       | `caas_destroy_deployment`         | Terminate a deployment and stop billing.           |
| **VMaaS**      | `vmaas_get_hardware_list`         | Browsing available GPU/CPU configurations.         |
| **VMaaS**      | `vmaas_deploy_vm`                 | Provision a VM cluster.                            |
| **VMaaS**      | `vmaas_list_deployments`          | Real-time status of your VM clusters.              |
| **VMaaS**      | `vmaas_get_deployment`            | Details of a single VM deployment.                 |
| **VMaaS**      | `vmaas_get_deployment_vms`        | VMs running inside a deployment.                   |
| **VMaaS**      | `vmaas_extend_cluster_duration`   | Add runtime to a VM cluster.                       |
| **VMaaS**      | `vmaas_destroy_deployment`        | Terminate a VM cluster and stop billing.           |

The recommended flow is: pick hardware from the catalog, estimate the price, deploy, then manage.

### Working with Hardware IDs

The catalog returns two kinds of hardware. Regional hardware uses string IDs and reports a `location` (for example `gpu_1x_a6000` in `US`, or `H100_sxm5x8` in `CA`); network hardware uses integer IDs with a null location.

What you can pass back depends on the service. `vmaas_deploy_vm` and `caas_get_price_estimate` accept either form, so pass the ID exactly as the catalog returned it and do not coerce a string ID to an integer. `caas_deploy_container` and `caas_get_available_replicas` currently accept integer IDs only, so pick a network hardware entry for those calls.

Every deploy needs a placement, so `location_ids` is not optional in practice: pass exactly one location, **or** a `node_pool_id` for a private node pool. Passing both is rejected, and so is passing neither. Only one location per deployment is supported today. `caas_get_price_estimate` requires `location_ids` as well. VMaaS accepts country codes such as `["US"]`; `caas_deploy_container` currently takes integer location IDs through this server.

<Warning>
  `duration_hours` on `caas_extend_deployment_duration` and `vmaas_extend_cluster_duration` is **additive**: it adds N hours to the time remaining, it does not set the new total. To reach a target total, subtract the current remaining hours yourself.
</Warning>

### Topping Up Credits with x402

When a deploy or extend is short on credits, IO Cloud answers with **x402**, the HTTP 402 payment protocol, so your agent can settle the bill and continue without a human opening the dashboard.

The four tools that spend credits (`caas_deploy_container`, `caas_extend_deployment_duration`, `vmaas_deploy_vm`, `vmaas_extend_cluster_duration`) return `status: "payment_required"` instead of an error. This is a bill to pay and then retry, not a failure.

Under `payment` you get a standard x402 envelope: `x402Version: 2`, an `accepts` array whose first entry uses the `exact` scheme, and an `io_net` object with the amounts in USD. Any x402-capable client can read it. Today the quote is payable in USDC on Solana, but take the chain and token from `accepts[0].network` and `accepts[0].asset` rather than assuming:

* Pay the exact `maxAmountRequired` of the given `asset`, to the exact `payTo` address, on the stated `network`. `maxAmountRequired` is in the asset's atomic units, so `"3820000"` means 3.82 USDC.
* Always take `payTo` from the response you are acting on. Never send to an address cached from an earlier call. A plain transfer with no memo matches correctly.
* Send the full amount in a single transfer. An underfunded intent is held without applying any credits until the full amount arrives.
* Top-ups have a \$1.00 minimum, so a shortfall under a dollar still requires a \$1 payment.

`io_net.shortfall_usd` is the gap between the request's cost and your balance. `io_net.quote_usd` is what the top-up actually costs, which is the shortfall grossed up for the payment provider's fee and floored at the minimum. Pay `quote_usd`, not `shortfall_usd`. Anything the top-up leaves over stays on your account as [IO Credits](/docs/guides/payment/io-credits).

### Authentication Methods

1. **Static Header (Recommended for Individuals):** Include your API key with `io-cloud` project scopes in the `x-api-key` HTTP header during setup.
2. **Dynamic Forwarding (For Multi-User Apps):** Pass the key dynamically within the `auth.api_key` argument of any specific tool call.

## Programmatic Usage (Python Example)

If you are building a custom integration, you can use the `mcp` Python SDK to interact with the IO Cloud server.

```python theme={null}
import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def io_cloud_demo():
    # 1. Initialize the HTTP Client
    async with streamablehttp_client("https://mcp.io.solutions/mcp") as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # 2. List available hardware via tool call
            # Note: We pass the API key dynamically here (Mode A)
            result = await session.call_tool(
                "vmaas_get_hardware_list", 
                arguments={
                    "auth": {"api_key": "YOUR_IO_NET_API_KEY"},
                    "gpu": "H100"
                }
            )
            print(f"Available H100s: {result}")

if __name__ == "__main__":
    asyncio.run(io_cloud_demo())
```

## Troubleshooting

* **Authentication Failure (401/403):** Verify your API key in the io.net dashboard.
* **"No API key provided":** Ensure the header is correctly set in your JSON config or passed in the tool arguments.
* **Connection Timeout:** Verify your network allows outbound traffic to `https://mcp.io.solutions`.
* **`status: "payment_required"`:** Your account is short on credits. Settle the x402 quote in the response, then retry the call.
* **Empty hardware list:** Filters match the catalog's own values. Use `gpu: "H100"`, not `gpu: "NVIDIA H100"`.

<Info>
  **Ready to scale your infrastructure?** For high-volume requirements or custom integration support, contact us at [support@io.net](mailto:support@io.net)
</Info>