---
sidebar_position: 9
title: "Lium MCP server: search and rent GPUs from Claude, ChatGPT and Codex"
sidebar_label: MCP Endpoint
description: "Connect Claude, ChatGPT, Codex or any MCP client to Lium at https://docs.lium.io/mcp to find GPUs with live prices. Sign in with Lium or send an API key to rent pods."
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lium.io/llms.txt
> Use this file to discover all available pages before exploring further.
>
> Lium (lium.io) is a GPU rental marketplace: rent NVIDIA GPUs by the hour, billed per second.

# Lium MCP server

The Lium docs site has a [Model Context Protocol](https://modelcontextprotocol.io) endpoint. Agents use it to search and read the docs, and to look up the GPUs rentable on Lium right now with their live prices. No sign-in needed. Signed in with Lium at `https://docs.lium.io/mcp/account` (Claude, ChatGPT) or with your [API key](../pod-users/api-keys) as a header (Claude Code, Codex), it also rents and removes pods.

:::info For agents
For the rest of the platform (volumes, backups, clusters), use the [API](./api) at `https://lium.io/api/openapi.json`.
:::

## Endpoint

```
POST https://docs.lium.io/mcp
```

MCP HTTP transport (JSON-RPC 2.0 over POST).

## Available tools

### `search`

Search all docs pages. Without an audience, pages for the other side (renter or provider, guessed from the query) rank lower.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query |
| `audience` | string | no | Filter to one audience: `providers`, `validators`, `pod-users`, `developers` |
| `limit` | number | no | Max results (default: 10) |

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "register a node",
      "audience": "providers",
      "limit": 5
    }
  }
}
```

### `read_page`

Read one page as markdown, by URL or slug.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url_or_slug` | string | yes | Full URL, absolute slug, or page basename |

**Example:**

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "read_page",
    "arguments": {
      "url_or_slug": "/providers/quickstart"
    }
  }
}
```

### `search_gpus`

GPU nodes rentable right now, cheapest per GPU-hour first, from the [public nodes feed](./public-nodes-feed). Each node carries its live price, tier (`secure` or `spot`), reliability score and a `rent_url`; rent one with `rent_pod`.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `gpu` | string | no | GPU model, e.g. `H100`, `B200`, `RTX 4090` (case and spacing ignored) |
| `count` | number | no | GPUs needed on one node; nodes that cannot rent that many are left out |
| `country` | string | no | Two-letter country code, e.g. `US` |
| `max_price_per_gpu_hour` | number | no | Price cap in USD per GPU-hour |
| `limit` | number | no | Max nodes (default: 10, max 50) |

### `get_gpu_prices`

Min, median and max USD price per GPU-hour and the free GPU count for each GPU model rentable right now. Optional `gpu`, `country` and `count` filters as above; pass `count` for a multi-GPU quote.

The feed is cached for 30 seconds; `generated_at` in each answer says when Lium produced it.

### `estimate_provider_earnings`

What a provider earns per month on Lium by listing `count` GPUs (default 1) of the model `gpu`, the same estimate as the [rewards calculator](https://provider.lium.io/rewards-calculator): rental income and rented extra at the last 30 days' utilisation, plus idle pay at the validator's rate for every unrented hour. It also gives what those GPUs actually earned, and the middle-half range across providers at full idle pay and rented extra: what they can earn, not actual payouts. An estimate, not a guarantee.

### Account tools

These need your Lium account on the connection: sign in at `https://docs.lium.io/mcp/account` (below), or send an API key (see **Connect with your API key**).

| Tool | What it does |
|------|--------------|
| `quote_rent` | Prices a rental before it is made, from the live nodes feed: GPU, count, USD per GPU-hour and per hour, and when billing starts. Rents nothing. Returns a `quote_id` and the exact `rent_pod` arguments (valid 30 to 60 minutes) |
| `rent_pod` | Rents a pod and waits up to 25 seconds by default (50 seconds max); returns the pod id and ssh command. Give `gpu` and `count` (Lium picks the cheapest node) or a `node_id` from `search_gpus`, a unique `idempotency_key`, `quoted_price_per_gpu_hour` and the `quote_id` that `quote_rent` returned for the same terms; other terms rent nothing, and a node asking more than one cent per GPU-hour above the quoted price is not rented. **Billed per second until `remove_pod`**; on any image other than the node's default, billing starts at the rent request, so startup time is billed too ([when a pod is charged](../pod-users/billing#when-a-pod-is-charged)). |
| `list_pods` | Your pods with status, ssh command and price per hour |
| `get_pod` | One pod by `pod_id` |
| `prepare_removal` | Lists what a removal would delete (name, id, GPU, status, price per hour, spend so far) for up to 50 `pod_ids`, with each pod's `removal_token` (valid 30 to 60 minutes). Removes nothing |
| `remove_pod` | Deletes one pod; billing stops when accepted. Takes `pod_id`, the pod's `pod_name` and the `removal_token` from `prepare_removal`, and removes nothing if either does not match. A bulk removal is one call per pod |
| `get_balance` | Your balance in USD |
| `list_templates` | Docker templates for `rent_pod`'s `template_id`; `official` marks Lium's, `yours` your own |

Renting and removing are two steps: `quote_rent` and `prepare_removal` show the exact targets and cost, and `rent_pod` and `remove_pod` act only with what they return, so the agent gets your yes first. The MCP cannot send, transfer or withdraw funds of any kind.

A [spend budget](../pod-users/api-keys) on the key caps what the agent can spend.

### Without renting: `/mcp/directory`

`https://docs.lium.io/mcp/directory` signs in like `/mcp/account` but issues a read-only key. It serves the docs and GPU tools plus `list_pods`, `get_pod` and `get_balance`; it cannot rent, remove pods or spend your balance.

## Connect with your API key

1. Create a key at [lium.io/api-keys](https://lium.io/api-keys) and add credit.
2. Add the endpoint with the header `Authorization: Bearer <your key>`.

**Claude Code**

```bash
claude mcp add --transport http lium https://docs.lium.io/mcp --header "Authorization: Bearer $LIUM_API_KEY"
```

**Codex CLI** (`~/.codex/config.toml`)

```toml
[mcp_servers.lium]
url = "https://docs.lium.io/mcp"
bearer_token_env_var = "LIUM_API_KEY"
```

**Other MCP clients**

```json
{
  "mcpServers": {
    "lium": {
      "url": "https://docs.lium.io/mcp",
      "headers": { "Authorization": "Bearer <your key>" }
    }
  }
}
```

## Use in Claude

**Claude (claude.ai or desktop)**

1. Open **Settings → Connectors**.
2. Click **Add custom connector**.
3. Enter `https://docs.lium.io/mcp/account` to rent pods (or `https://docs.lium.io/mcp` for the docs and GPU prices only, no sign-in), leave the OAuth settings empty, and click **Add**.
4. For `/mcp/account`, click **Connect**, check the page says you return to **claude.ai**, then sign in on lium.io and approve.
5. In a chat, turn the connector on from the tools menu.

The approval creates an API key named `lium CLI MCP Claude …` on [lium.io/api-keys](https://lium.io/api-keys). Delete it there to disconnect; set a [budget](../pod-users/api-keys#budgets) on it to cap spend.

**Claude Code**

```bash
claude mcp add --transport http lium-docs https://docs.lium.io/mcp
```

**Other MCP clients**

```json
{
  "mcpServers": {
    "lium-docs": {
      "url": "https://docs.lium.io/mcp"
    }
  }
}
```

**ChatGPT**

1. Turn on developer mode in **Settings → Apps → Advanced settings**.
2. Create an app with the URL `https://docs.lium.io/mcp/account` and authentication **OAuth** to rent pods (or `https://docs.lium.io/mcp` and no authentication for the docs only).
3. Click **Connect**, sign in on lium.io and approve.
4. Enable it in a chat. If the app is not connected, an account tool shows **Sign in with Lium** in the chat.

Limit: 600 requests per minute per IP address.

## `.md` URLs

Add `.md` to any docs URL to get the page as markdown:

```bash
curl https://docs.lium.io/providers/quickstart.md
```

Or send `Accept: text/markdown`:

```bash
curl -H 'Accept: text/markdown' https://docs.lium.io/providers/quickstart
```
