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

# Storage

[Back to the MCP tool reference](/index/apolo-mcp/capabilities/tools.md).

## `list_storage`

List a bounded storage directory; the response marks truncation.

**Operation type:** <mark style="background-color:blue;">Read-only</mark>

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "default": "",
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "title": "list_storageArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "list_storageDictOutput",
  "type": "object"
}
```

## `stat_storage`

Return metadata for one exact storage path.

**Operation type:** <mark style="background-color:blue;">Read-only</mark>

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "path"
  ],
  "title": "stat_storageArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "stat_storageDictOutput",
  "type": "object"
}
```

## `read_text`

Read a UTF-8 text prefix under a strict byte cap.

**Operation type:** <mark style="background-color:blue;">Read-only</mark>

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "max_bytes": {
      "default": 65536,
      "title": "Max Bytes",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "path"
  ],
  "title": "read_textArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "read_textDictOutput",
  "type": "object"
}
```

## `write_text`

Create or update a small UTF-8 object under server policy.

**Operation type:** <mark style="background-color:green;">Write</mark>

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "content": {
      "title": "Content",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "path",
    "content"
  ],
  "title": "write_textArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "write_textDictOutput",
  "type": "object"
}
```

## `upload_storage_file`

Upload one local file to an exact storage path. File bytes are never serialized through MCP. Existing remote files may be overwritten only under full or exact ledger-owned managed policy. An optional positive timeout can bound the transfer when requested by the caller.

**Operation type:** <mark style="background-color:green;">Write</mark>

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "local_path": {
      "title": "Local Path",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Timeout Seconds"
    }
  },
  "required": [
    "local_path",
    "path"
  ],
  "title": "upload_storage_fileArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "upload_storage_fileDictOutput",
  "type": "object"
}
```

## `download_storage_file`

Download one storage file to a new confined local file. Existing local files are never overwritten and file bytes are never serialized through MCP. An optional positive timeout can bound the transfer when requested by the caller.

**Operation type:** <mark style="background-color:green;">Write</mark>

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "local_path": {
      "title": "Local Path",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Timeout Seconds"
    }
  },
  "required": [
    "path",
    "local_path"
  ],
  "title": "download_storage_fileArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "download_storage_fileDictOutput",
  "type": "object"
}
```

## `make_directory`

Create an exact directory under server policy.

**Operation type:** <mark style="background-color:green;">Write</mark>

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "exist_ok": {
      "default": true,
      "title": "Exist Ok",
      "type": "boolean"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "parents": {
      "default": true,
      "title": "Parents",
      "type": "boolean"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "path"
  ],
  "title": "make_directoryArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "make_directoryDictOutput",
  "type": "object"
}
```

## `delete_storage_path`

Delete one exact path; recursive deletion removes its entire subtree.

**Operation type:** <mark style="background-color:yellow;">Destructive write</mark>

**Annotations:** read-only `false`, destructive `true`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "recursive": {
      "default": false,
      "title": "Recursive",
      "type": "boolean"
    }
  },
  "required": [
    "path"
  ],
  "title": "delete_storage_pathArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "delete_storage_pathDictOutput",
  "type": "object"
}
```