MCP Tools Reference: storage.googleapis.com

Tool: list_objects

Lists the objects in a bucket.

The following code sample shows how to use curl to call the list_objects MCP tool.

Curl Request 
curl --location 'https://storage.googleapis.com/storage/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_objects",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

ListObjectsRequest

JSON representation 
{
  "bucketName": string,
  "prefix": string,
  "recursive": boolean,
  "pageSize": integer,
  "pageToken": string
}
Fields
bucketName

string

Required. The name of the bucket to list objects in. Format: {bucket_id}
prefix

string

Optional. The prefix to filter objects by. If not specified, all objects are matched. If recursive is false, only objects at the same level as the prefix are matched. For instance, if recursive is false, "documents" will match "documents.txt" but not "documents/my-file.txt".
recursive

boolean

Optional. Indicates whether the list operation should be recursive, including objects in subdirectories. If false (default), only objects directly within the specified prefix are listed.
pageSize

integer

Optional. The maximum number of objects to return. The service can return fewer than this value.

If unspecified, at most 1000 objects will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.
pageToken

string

Optional. A page token, received from a previous ListObjects call. Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListObjects must match the call that provided the page token (except pageSize, which can differ).

Output Schema

Response message for ListObjects.

ListObjectsResponse

JSON representation 
{
  "objectNames": [
    string
  ],
  "prefixes": [
    string
  ],
  "nextPageToken": string,
  "objects": [
    {
      object (Object)
    }
  ]
}
Fields
objectNames[]

string

The list of objects, ordered lexicographically by name. At most 1000 objects are returned.
prefixes[]

string

Object name prefixes for objects that matched the listing request but were excluded from objectNames because recursive is false. Values in this list are object names up to and including the delimiter /. Duplicate entries are omitted from this list. Ordered lexicographically. At most 1000 prefixes are returned.
nextPageToken

string

A token, which can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.
objects[]

object (Object)

Detailed metadata for the returned objects.

Object

JSON representation 
{
  "bucketName": string,
  "objectName": string,
  "contentType": string,
  "size": string,
  "storageClass": string,
  "timeCreated": string,
  "timeLastModified": string,
  "generation": string,
  "metageneration": string,
  "etag": string,
  "checksums": {
    object (ObjectChecksumsMetadata)
  },
  "contentEncoding": string,
  "contentDisposition": string,
  "contentLanguage": string,
  "cacheControl": string,
  "customTime": string,
  "softDeleteTime": string,
  "retentionExpireTime": string,
  "kmsKeyName": string,
  "customerEncryption": {
    object (CustomerEncryptionMetadata)
  },
  "temporaryHold": boolean,
  "eventBasedHold": boolean,
  "retention": {
    object (ObjectRetentionMetadata)
  },
  "metadata": {
    string: string,
    ...
  },
  "componentCount": integer
}
Fields
bucketName

string

The name of the bucket containing this object.
objectName

string

The name of this object. Nearly any sequence of unicode characters is valid. See Guidelines.
contentType

string

Content-Type of the object data, matching RFC 7231 §3.1.1.5. If an object is stored without a Content-Type, it is served as application/octet-stream.
size

string (int64 format)

Content-Length of the object data in bytes, matching RFC 7230 §3.3.2.
storageClass

string

Storage class of the object.
timeCreated

string (Timestamp format)

The creation time of the object.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
timeLastModified

string (Timestamp format)

The modification time of the object metadata. Set initially to object creation time and then updated whenever any metadata of the object changes.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
generation

string (int64 format)

The content generation of this object. Used for object versioning.
metageneration

string (int64 format)

The version of the metadata for this generation of this object. Used for preconditions and for detecting changes in metadata.
etag

string

The etag of an object.
checksums

object (ObjectChecksumsMetadata)

Hashes for the data part of this object.
contentEncoding

string

Content-Encoding of the object data, matching RFC 7231 §3.1.2.2.
contentDisposition

string

Content-Disposition of the object data, matching RFC 6266.
contentLanguage

string

Content-Language of the object data, matching RFC 7231 §3.1.3.2.
cacheControl

string

Cache-Control directive for the object data, matching RFC 7234 §5.2. If omitted, and the object is accessible to all anonymous users, the default is public, max-age=3600.
customTime

string (Timestamp format)

A user-specified timestamp set on an object.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
softDeleteTime

string (Timestamp format)

The time when the object became soft-deleted.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
retentionExpireTime

string (Timestamp format)

A server-determined value that specifies the earliest time that the object's retention period expires.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
kmsKeyName

string

Cloud KMS Key used to encrypt this object, if the object is encrypted by such a key.
customerEncryption

object (CustomerEncryptionMetadata)

Metadata of customer-supplied encryption key, if the object is encrypted by such a key.
temporaryHold

boolean

Whether an object is under temporary hold. While this flag is set to true, the object is protected against deletion and overwrites.
eventBasedHold

boolean

Whether an object is under event-based hold.
retention

object (ObjectRetentionMetadata)

Retention configuration of this object.
metadata

map (key: string, value: string)

User-provided metadata, in key/value pairs.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
componentCount

integer

Number of underlying components that make up this object. Components are accumulated by compose operations.

Timestamp

JSON representation 
{
  "seconds": string,
  "nanos": integer
}
Fields
seconds

string (int64 format)

Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z).
nanos

integer

Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive.

ObjectChecksumsMetadata

JSON representation 
{
  "md5Hash": string,

  // Union field _crc32c can be only one of the following:
  "crc32c": integer
  // End of list of possible types for union field _crc32c.
}
Fields
md5Hash

string (bytes format)

A base64-encoded string.

Union field _crc32c.

_crc32c can be only one of the following:
crc32c

integer

CustomerEncryptionMetadata

JSON representation 
{
  "encryptionAlgorithm": string,
  "keySha256Bytes": string
}
Fields
encryptionAlgorithm

string
keySha256Bytes

string (bytes format)

A base64-encoded string.

ObjectRetentionMetadata

JSON representation 
{
  "mode": enum (Mode),
  "retainUntilTime": string
}
Fields
mode

enum (Mode)
retainUntilTime

string (Timestamp format)

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

MetadataEntry

JSON representation 
{
  "key": string,
  "value": string
}
Fields
key

string
value

string

Mode

Enums
MODE_UNSPECIFIED
UNLOCKED
LOCKED

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌