> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/mcp/tools/catalog.md).

# Catalog and marketplace

Find provider regions and instance types, or browse marketplace capacity.

Find provider regions and instance types, or browse marketplace capacity.

These are action names. In default compact mode, call the indicated group tool with `{"action":"<action-name>","params":{...}}`; the arguments below go inside `params`. In `?mode=all`, call the action name directly with those arguments. `browse_github` and `read_docs` are direct tools in both modes. Expand each schema for nested fields, enum values and validation constraints. Successful results are JSON in both text content and `structuredContent`; failures use `isError` and `structuredContent.error`.

The [OpenAI profile](/mcp/openai-profile.md) calls individual actions, omits `get_byod_token`, and restricts credential inputs and environment outputs. The input schemas below describe the standard catalog; profile-specific schemas are included where they differ.

## `browse_catalog`

What a cloud provider can provision: regions, zones and instance types. kind=regions lists regions (with the default one), kind=zones the availability zones of a region, kind=instance\_types the instance types of a region (popular picks by default, a search, or everything with all=true). Ids from here feed provision\_servers.

**Group:** `catalog` · **Behavior:** Read

**Compact tool:** `catalog` · **Action:** `browse_catalog`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation               | REST                                                 | Required scopes |
| ----------------------- | ---------------------------------------------------- | --------------- |
| `catalog.regions`       | `GET /catalog/{csp}/regions`                         | `pools:read`    |
| `catalog.zones`         | `GET /catalog/{csp}/regions/{region}/zones`          | `pools:read`    |
| `catalog.instanceTypes` | `GET /catalog/{csp}/regions/{region}/instance-types` | `pools:read`    |

### Arguments

| Argument | Type                                     | Required | Description                                               |
| -------- | ---------------------------------------- | -------- | --------------------------------------------------------- |
| `kind`   | `"regions" / "zones" / "instance_types"` | Yes      | Which part of the catalog to list                         |
| `csp`    | `"kinesis" / "aws" / "azure"`            | Yes      | Cloud provider                                            |
| `region` | `string`                                 | No       | Provider region id; required for zones and instance types |
| `zone`   | `string`                                 | No       | Limit to one availability zone                            |
| `search` | `string`                                 | No       | Substring to search names and GPU types for               |
| `all`    | `boolean`                                | No       | List the full catalog instead of the popular picks        |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "regions",
        "zones",
        "instance_types"
      ],
      "description": "Which part of the catalog to list"
    },
    "csp": {
      "type": "string",
      "enum": [
        "kinesis",
        "aws",
        "azure"
      ],
      "description": "Cloud provider"
    },
    "region": {
      "description": "Provider region id; required for zones and instance types",
      "type": "string",
      "minLength": 1
    },
    "zone": {
      "type": "string",
      "minLength": 1,
      "description": "Limit to one availability zone"
    },
    "search": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Substring to search names and GPU types for"
    },
    "all": {
      "type": "boolean",
      "description": "List the full catalog instead of the popular picks"
    }
  },
  "required": [
    "kind",
    "csp"
  ],
  "additionalProperties": false
}
```

</details>

### Result

**`catalog.regions`**

* `regions` (`array<object>`): See the complete response schema below.
* `defaultRegion` (`string`): Region id chosen by default

<details>

<summary>Response schema: catalog.regions</summary>

```json
{
  "type": "object",
  "properties": {
    "regions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Region id to use when provisioning"
          },
          "name": {
            "type": "string"
          },
          "location": {
            "type": "string",
            "description": "City or area"
          },
          "recommended": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "name",
          "location",
          "recommended"
        ],
        "additionalProperties": false
      }
    },
    "defaultRegion": {
      "type": "string",
      "description": "Region id chosen by default"
    }
  },
  "required": [
    "regions",
    "defaultRegion"
  ],
  "additionalProperties": false
}
```

</details>

\*\*\`catalog.zones\`\*\*

* `zones` (`array<object>`): See the complete response schema below.

<details>

<summary>Response schema: catalog.zones</summary>

```json
{
  "type": "object",
  "properties": {
    "zones": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "zones"
  ],
  "additionalProperties": false
}
```

</details>

\*\*\`catalog.instanceTypes\`\*\*

* `instanceTypes` (`array<object>`): Cheapest first

<details>

<summary>Response schema: catalog.instanceTypes</summary>

```json
{
  "type": "object",
  "properties": {
    "instanceTypes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Instance type id to use when provisioning"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "description": "General Purpose, Compute Optimized, GPU, ..."
          },
          "specs": {
            "type": "object",
            "properties": {
              "vCpus": {
                "type": "number"
              },
              "memory": {
                "type": "string",
                "description": "Human-readable, e.g. 8 GiB"
              },
              "storage": {
                "type": "string"
              },
              "networkPerformance": {
                "type": "string"
              },
              "gpuType": {
                "type": "string"
              },
              "gpuManufacturer": {
                "type": "string"
              },
              "gpuCount": {
                "type": "number"
              },
              "gpuMemory": {
                "type": "string"
              }
            },
            "required": [
              "vCpus",
              "memory"
            ],
            "additionalProperties": false
          },
          "pricePerHour": {
            "type": "number",
            "description": "Customer price in USD per hour"
          },
          "inStock": {
            "description": "null when the provider does not report stock",
            "type": [
              "boolean",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "name",
          "category",
          "specs",
          "pricePerHour",
          "inStock"
        ],
        "additionalProperties": false
      },
      "description": "Cheapest first"
    }
  },
  "required": [
    "instanceTypes"
  ],
  "additionalProperties": false
}
```

</details>

## `browse_marketplace`

Browse spot capacity on the marketplace by hardware profile and country

**Group:** `catalog` · **Behavior:** Read

**Compact tool:** `catalog` · **Action:** `browse_marketplace`

**MCP annotations:** `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Permissions and REST equivalents

| Operation            | REST               | Required scopes |
| -------------------- | ------------------ | --------------- |
| `marketplace.browse` | `GET /marketplace` | `pools:read`    |

### Arguments

| Argument            | Type            | Required | Description                                  |
| ------------------- | --------------- | -------- | -------------------------------------------- |
| `gpuTypes`          | `array<string>` | No       | GPU models to include, e.g. H100             |
| `noGpu`             | `boolean`       | No       | CPU-only machines                            |
| `gpusPerMachine`    | `integer`       | No       | Exact GPU count per machine                  |
| `minCpus`           | `integer`       | No       | Minimum physical CPU packages                |
| `minRamGb`          | `integer`       | No       | Minimum RAM in GB                            |
| `minStorageGb`      | `integer`       | No       | Minimum disk in GB                           |
| `location`          | `string`        | No       | Marketplace location key                     |
| `vettedOnly`        | `boolean`       | No       | Only machines from vetted providers          |
| `tierIds`           | `array<string>` | No       | Provider tiers to include                    |
| `minGuaranteedDays` | `integer`       | No       | Minimum availability guarantee               |
| `minNoticeHours`    | `integer`       | No       | Minimum notice before a machine is withdrawn |

<details>

<summary>Complete input schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "gpuTypes": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "GPU models to include, e.g. H100"
    },
    "noGpu": {
      "type": "boolean",
      "description": "CPU-only machines"
    },
    "gpusPerMachine": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Exact GPU count per machine"
    },
    "minCpus": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Minimum physical CPU packages"
    },
    "minRamGb": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Minimum RAM in GB"
    },
    "minStorageGb": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Minimum disk in GB"
    },
    "location": {
      "type": "string",
      "minLength": 1,
      "description": "Marketplace location key"
    },
    "vettedOnly": {
      "type": "boolean",
      "description": "Only machines from vetted providers"
    },
    "tierIds": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Provider tiers to include"
    },
    "minGuaranteedDays": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Minimum availability guarantee"
    },
    "minNoticeHours": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Minimum notice before a machine is withdrawn"
    }
  },
  "additionalProperties": false
}
```

</details>

### Result

* `listings` (`array<object>`): See the complete response schema below.
* `summary` (`object`): See the complete response schema below.
* `truncated` (`boolean`): The scan hit its cap; counts are lower bounds

<details>

<summary>Response schema: marketplace.browse</summary>

```json
{
  "type": "object",
  "properties": {
    "listings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "configId": {
            "type": "string",
            "description": "Stable id of this hardware profile and country bucket"
          },
          "hardwareProfile": {
            "type": "string"
          },
          "gpuModel": {
            "description": "null for CPU-only machines",
            "type": [
              "string",
              "null"
            ]
          },
          "gpusPerMachine": {
            "type": "integer"
          },
          "vramGbPerGpu": {
            "type": "number"
          },
          "cpuThreads": {
            "type": "number"
          },
          "minCpuPackages": {
            "description": "Smallest physical CPU count in the bucket",
            "type": "number"
          },
          "ramGb": {
            "type": "number"
          },
          "storageGb": {
            "type": "number"
          },
          "countryCode": {
            "type": "string",
            "description": "ISO country code; empty when unreported"
          },
          "locationLabel": {
            "type": "string"
          },
          "tierIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "isVetted": {
            "type": "boolean"
          },
          "totalMachines": {
            "type": "integer"
          },
          "availableMachines": {
            "type": "integer"
          },
          "minPriceCentsPerHour": {
            "type": "number",
            "description": "Cheapest machine-hour in the bucket"
          },
          "maxPriceCentsPerHour": {
            "type": "number"
          },
          "pricePerGpuHourCents": {
            "type": "number"
          },
          "guaranteedDays": {
            "description": "Weakest availability guarantee in the bucket",
            "type": "number"
          },
          "isOpenEnded": {
            "type": "boolean",
            "description": "Every machine is available until its provider changes its mind"
          },
          "noticeHours": {
            "type": "number"
          }
        },
        "required": [
          "configId",
          "hardwareProfile",
          "gpuModel",
          "gpusPerMachine",
          "countryCode",
          "locationLabel",
          "tierIds",
          "isVetted",
          "totalMachines",
          "availableMachines",
          "minPriceCentsPerHour",
          "maxPriceCentsPerHour",
          "isOpenEnded",
          "noticeHours"
        ],
        "additionalProperties": false
      }
    },
    "summary": {
      "type": "object",
      "properties": {
        "availableMachines": {
          "type": "integer"
        },
        "configurations": {
          "type": "integer"
        },
        "fromPriceCentsPerGpuHour": {
          "type": "number"
        },
        "fromPriceCentsPerHour": {
          "type": "number"
        }
      },
      "required": [
        "availableMachines",
        "configurations"
      ],
      "additionalProperties": false
    },
    "truncated": {
      "type": "boolean",
      "description": "The scan hit its cap; counts are lower bounds"
    }
  },
  "required": [
    "listings",
    "summary",
    "truncated"
  ],
  "additionalProperties": false
}
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kinesis.network/mcp/tools/catalog.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.