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

# Tool Reference

Detailed reference for all 10 tools exposed by the RunComfy MCP server. Each tool maps directly to a **[Serverless API (ComfyUI)](/serverless/introduction)** endpoint.

***

## Deployment management

### `list_deployments`

List all Serverless API deployments in your account.

**Backs**: `GET /prod/v2/deployments`

| Parameter         | Type      | Required | Description                                                     |
| ----------------- | --------- | :------: | --------------------------------------------------------------- |
| `ids`             | string\[] |    No    | Filter to specific deployment IDs                               |
| `include_payload` | boolean   |    No    | Include `workflow_api_json`, `overrides`, and `object_info_url` |
| `include_readme`  | boolean   |    No    | Include the deployment's README markdown                        |

**Example arguments:**

```json theme={null}
{}
```

**Example response (structuredContent):**

```json theme={null}
{
  "ok": true,
  "deployments": [
    {
      "id": "a1b2c3d4-...",
      "name": "text-to-image",
      "workflow_id": "00000000-...",
      "workflow_version": "v1",
      "hardware": ["AMPERE_48"],
      "min_instances": 0,
      "max_instances": 1,
      "status": "standby",
      "is_enabled": true
    }
  ]
}
```

***

### `get_deployment`

Get one deployment by ID, optionally including its full workflow graph.

**Backs**: `GET /prod/v2/deployments/{deployment_id}`

| Parameter         | Type    | Required | Description                                                                                       |
| ----------------- | ------- | :------: | ------------------------------------------------------------------------------------------------- |
| `deployment_id`   | string  |    Yes   | The deployment's UUID                                                                             |
| `include_payload` | boolean |    No    | Include `workflow_api_json` and node schemas — use this to discover node IDs for `submit_request` |
| `include_readme`  | boolean |    No    | Include the deployment's README                                                                   |

> Tip: Call with `include_payload=true` to see every node's ID and input names. Use those to build the `overrides` object for `submit_request`.

**Example arguments:**

```json theme={null}
{
  "deployment_id": "a1b2c3d4-...",
  "include_payload": true
}
```

***

### `create_deployment`

Create a new Serverless API (ComfyUI) deployment from a cloud-saved workflow.

**Backs**: `POST /prod/v2/deployments`

| Parameter                       | Type    | Required | Default       | Description                                  |
| ------------------------------- | ------- | :------: | ------------- | -------------------------------------------- |
| `name`                          | string  |    Yes   | —             | Human-readable name                          |
| `workflow_id`                   | string  |    Yes   | —             | UUID of the ComfyUI workflow                 |
| `workflow_version`              | string  |    Yes   | —             | Version label (e.g., `"v1"`)                 |
| `hardware`                      | string  |    No    | `"AMPERE_48"` | GPU SKU (see hardware table below)           |
| `min_instances`                 | integer |    No    | `0`           | Warm instance floor (0–30). Billable if > 0. |
| `max_instances`                 | integer |    No    | `1`           | Concurrency ceiling (1–60)                   |
| `queue_size`                    | integer |    No    | `1`           | Pending requests per instance before scaling |
| `keep_warm_duration_in_seconds` | integer |    No    | `60`          | Idle timeout before scale-down               |

**Hardware SKUs:**

```
TURING_16  |  AMPERE_24  |  AMPERE_48  |  ADA_48_PLUS
AMPERE_80  |  ADA_80_PLUS  |  HOPPER_141
```

**Example arguments:**

```json theme={null}
{
  "name": "my-flux-deployment",
  "workflow_id": "00000000-0000-0000-0000-000000001234",
  "workflow_version": "v1",
  "hardware": "AMPERE_48",
  "min_instances": 0,
  "max_instances": 2
}
```

> For LoRA deployments, create via the RunComfy UI (Trainer > LoRA Assets > Deploy), then use `list_deployments` to get the `deployment_id`.

***

### `update_deployment`

Partially update a deployment. Only pass the fields you want to change.

**Backs**: `PATCH /prod/v2/deployments/{deployment_id}`

| Parameter                       | Type    | Required | Description                        |
| ------------------------------- | ------- | :------: | ---------------------------------- |
| `deployment_id`                 | string  |    Yes   | The deployment's UUID              |
| `name`                          | string  |    No    | New name                           |
| `workflow_version`              | string  |    No    | New version label                  |
| `hardware`                      | string  |    No    | New GPU SKU                        |
| `min_instances`                 | integer |    No    | New warm floor                     |
| `max_instances`                 | integer |    No    | New concurrency ceiling            |
| `queue_size`                    | integer |    No    | New queue threshold                |
| `keep_warm_duration_in_seconds` | integer |    No    | New idle timeout                   |
| `is_enabled`                    | boolean |    No    | `false` to pause, `true` to resume |

**Example — pause a deployment:**

```json theme={null}
{
  "deployment_id": "a1b2c3d4-...",
  "is_enabled": false
}
```

***

### `delete_deployment`

Permanently delete a deployment. This cannot be undone.

**Backs**: `DELETE /prod/v2/deployments/{deployment_id}`

| Parameter       | Type   | Required | Description           |
| --------------- | ------ | :------: | --------------------- |
| `deployment_id` | string |    Yes   | The deployment's UUID |

> Consider `update_deployment` with `is_enabled=false` to pause instead of deleting.

***

## Inference

### `submit_request`

Submit an async inference request to a deployment.

**Backs**: `POST /prod/v2/deployments/{deployment_id}/inference`

| Parameter                     | Type    | Required | Description                                                               |
| ----------------------------- | ------- | :------: | ------------------------------------------------------------------------- |
| `deployment_id`               | string  |    Yes   | Target deployment                                                         |
| `overrides`                   | object  |    No    | Partial workflow graph keyed by node ID (see example below)               |
| `workflow_api_json`           | object  |    No    | Advanced: run a different workflow inline without updating the deployment |
| `extra_data`                  | object  |    No    | E.g., `{"api_key_comfy_org": "comfyui-..."}` for ComfyUI Core API nodes   |
| `webhook_url`                 | string  |    No    | URL for push-based status updates                                         |
| `webhook_intermediate_status` | boolean |    No    | Fire webhooks on every status change, not just terminal                   |
| `wait_for_completion`         | boolean |    No    | If `true`, poll until done and return the result inline                   |
| `timeout_seconds`             | integer |    No    | Max wait (default 300) when `wait_for_completion=true`                    |

**Example — text-to-image with overrides:**

```json theme={null}
{
  "deployment_id": "a1b2c3d4-...",
  "overrides": {
    "6": {
      "inputs": {
        "text": "a futuristic cityscape at sunset"
      }
    },
    "31": {
      "inputs": {
        "seed": 42
      }
    }
  }
}
```

**File inputs** — pass a public URL or Base64 data URI directly in the overrides value:

```json theme={null}
{
  "deployment_id": "a1b2c3d4-...",
  "overrides": {
    "189": {
      "inputs": {
        "image": "https://example.com/input-photo.jpg"
      }
    }
  }
}
```

Or using Base64:

```json theme={null}
{
  "deployment_id": "a1b2c3d4-...",
  "overrides": {
    "189": {
      "inputs": {
        "image": "data:image/jpeg;base64,/9j/4AAQ..."
      }
    }
  }
}
```

> Use `get_deployment` with `include_payload=true` to discover the node IDs and input names for your workflow.

***

### `get_request_status`

Poll a request's current status.

**Backs**: `GET /prod/v2/deployments/{deployment_id}/requests/{request_id}/status`

| Parameter       | Type   | Required | Description                                 |
| --------------- | ------ | :------: | ------------------------------------------- |
| `deployment_id` | string |    Yes   | The deployment that owns this request       |
| `request_id`    | string |    Yes   | The request ID returned by `submit_request` |

Status lifecycle: `in_queue` > `in_progress` > `completed` (or `cancelled`).

**Example response:**

```json theme={null}
{
  "ok": true,
  "status": {
    "request_id": "5f1ba692-...",
    "status": "in_progress",
    "queue_position": null,
    "instance_id": "1697cb1a-..."
  }
}
```

***

### `get_request_result`

Fetch the final outputs of a completed request.

**Backs**: `GET /prod/v2/deployments/{deployment_id}/requests/{request_id}/result`

| Parameter       | Type   | Required | Description                           |
| --------------- | ------ | :------: | ------------------------------------- |
| `deployment_id` | string |    Yes   | The deployment that owns this request |
| `request_id`    | string |    Yes   | The request ID                        |

Output URLs are hosted for **7 days** after success. Download or copy them to your own storage for longer retention.

**Example response:**

```json theme={null}
{
  "ok": true,
  "result": {
    "request_id": "5f1ba692-...",
    "status": "succeeded",
    "outputs": {
      "9": {
        "images": [
          {
            "url": "https://serverless-api-storage.runcomfy.net/.../ComfyUI_00001_.png",
            "filename": "ComfyUI_00001_.png"
          }
        ]
      }
    },
    "created_at": "2026-04-16T03:40:52.093Z",
    "finished_at": "2026-04-16T03:44:18.401Z"
  },
  "output_urls": [
    {
      "node_id": "9",
      "channel": "images",
      "url": "https://serverless-api-storage.runcomfy.net/.../ComfyUI_00001_.png",
      "filename": "ComfyUI_00001_.png"
    }
  ]
}
```

***

### `cancel_request`

Cancel a queued or running request.

**Backs**: `POST /prod/v2/deployments/{deployment_id}/requests/{request_id}/cancel`

| Parameter       | Type   | Required | Description                           |
| --------------- | ------ | :------: | ------------------------------------- |
| `deployment_id` | string |    Yes   | The deployment that owns this request |
| `request_id`    | string |    Yes   | The request ID                        |

Returns `cancelled` if accepted, or `not_cancellable` if the request has already completed.

**Example response:**

```json theme={null}
{
  "ok": true,
  "cancel": {
    "request_id": "5f1ba692-...",
    "status": "completed",
    "outcome": "cancelled"
  }
}
```

***

## Advanced

### `call_instance_proxy`

Call a ComfyUI backend endpoint on a live instance.

**Backs**: `POST /prod/v2/deployments/{deployment_id}/instances/{instance_id}/proxy/{comfy_backend_path}`

| Parameter            | Type   | Required | Description                                                                   |
| -------------------- | ------ | :------: | ----------------------------------------------------------------------------- |
| `deployment_id`      | string |    Yes   | The deployment                                                                |
| `instance_id`        | string |    Yes   | The running instance (from `get_request_status` when status is `in_progress`) |
| `comfy_backend_path` | string |    Yes   | The ComfyUI backend route, e.g., `api/free`                                   |
| `request_body`       | object |    No    | JSON body to send to the ComfyUI endpoint                                     |

**Example — unload models to free GPU memory:**

```json theme={null}
{
  "deployment_id": "a1b2c3d4-...",
  "instance_id": "1697cb1a-...",
  "comfy_backend_path": "api/free",
  "request_body": {
    "unload_models": true,
    "free_memory": true
  }
}
```

> Instance IDs are ephemeral — they are only valid while the instance is running. If the instance shuts down, submit a new request to get a fresh instance.