This page is the complete parameter and return-type reference for all 10 R2 object tools registered by the Cloudflare R2 Remote MCP Worker. Every input is validated with a Zod schema at call time; each tool returns a typed JSON result or surfaces a structuredDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/xxyoudeadpunkxx/cloudflare-r2-remote-mcp-worker/llms.txt
Use this file to discover all available pages before exploring further.
R2McpError with a machine-readable code and HTTP status.
r2_object_list
List objects stored under the configuredR2_ROOT_PREFIX. Results are always scoped to the root prefix — keys returned in objects are relative to that prefix.
Parameters
Filter results to keys that begin with this prefix, relative to
R2_ROOT_PREFIX. Omit to list all objects in the bucket scope.Maximum number of objects to return. Must be between
1 and MAX_LIST_LIMIT (default 100). Defaults to MAX_LIST_LIMIT when omitted.Opaque pagination cursor returned in a previous truncated response. Pass this value to fetch the next page of results.
Single-character delimiter used to group keys into virtual directories. Maximum length: 1 character. Common value:
"/".Returns
Array of object metadata records for each key in the page. See ObjectMetadata type for field details.
Common key prefixes collapsed by the
delimiter, relative to R2_ROOT_PREFIX. Empty when delimiter is not provided.true when more results exist beyond this page. Use the returned cursor to fetch the next page.Opaque pagination cursor. Present only when
truncated is true.The resolved
R2_ROOT_PREFIX in effect for this call. Useful for debugging scope.Error codes
This tool returns an empty result set rather than an error when the bucket is empty or no objects match the prefix. NoR2McpError codes are raised under normal conditions.
r2_object_head
Return metadata for a single R2 object without downloading its body. Equivalent to an HTTPHEAD request.
Parameters
Relative object key, scoped to
R2_ROOT_PREFIX. Must not contain .., null bytes, or be an absolute path.Returns
Returns an ObjectMetadata object directly.Relative object key.
Object size in bytes.
MIME type stored with the object, or
null if not set.ETag of the stored object.
ISO 8601 timestamp of the last write, or
null if unavailable.Key-value pairs of custom metadata attached to the object.
Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
object_not_found | 404 | No object exists at the given key. |
r2_object_get
Read the body of a text-like R2 object. The tool checks that the object’scontentType is text-like (e.g. text/*, application/json, application/yaml, etc.) and that its size does not exceed MAX_INLINE_TEXT_BYTES (default 256 KiB) before fetching.
Parameters
Relative object key, scoped to
R2_ROOT_PREFIX.Returns
Relative object key.
UTF-8 decoded body of the object.
MIME type of the object, or
null if not set.ETag of the stored object.
Object size in bytes.
ISO 8601 timestamp of the last write, or
null if unavailable.Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
object_not_found | 404 | No object exists at the given key. |
unsupported_content_type | 415 | Object has a binary or unsupported MIME type. Use r2_download_base64 instead. |
payload_too_large | 413 | Object size exceeds MAX_INLINE_TEXT_BYTES. |
r2_object_put
Write a UTF-8 text string to an R2 object. Optionally supplyexpectedEtag to perform a conditional overwrite — the write is rejected if the stored ETag does not match.
Parameters
Relative object key, scoped to
R2_ROOT_PREFIX.UTF-8 text body to store. The UTF-8 encoded byte length must not exceed
MAX_TRANSFER_BYTES (default 1 MiB).MIME type to store with the object (e.g.
text/plain, application/json).Arbitrary string key-value pairs to attach as custom metadata.
If provided, the write only succeeds when the current stored ETag matches this value exactly. Use
"*" to require that the object already exists.Returns
Returns the ObjectMetadata of the newly written object.Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
payload_too_large | 413 | UTF-8 encoded text exceeds MAX_TRANSFER_BYTES. |
etag_conflict | 409 | expectedEtag was supplied and the current ETag did not match. |
invalid_path | 400 | Key contains .., null bytes, or is otherwise invalid. |
r2_object_put_if_absent
Write a UTF-8 text object only when no object currently exists at the given key. Internally uses R2’setagDoesNotMatch: "*" condition.
Parameters
Relative object key, scoped to
R2_ROOT_PREFIX.UTF-8 text body to store. The UTF-8 encoded byte length must not exceed
MAX_TRANSFER_BYTES.MIME type to store with the object.
Arbitrary string key-value pairs to attach as custom metadata.
Returns
Returns the ObjectMetadata of the newly created object.Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
payload_too_large | 413 | UTF-8 encoded text exceeds MAX_TRANSFER_BYTES. |
object_already_exists | 409 | An object already exists at the given key. |
invalid_path | 400 | Key contains .., null bytes, or is otherwise invalid. |
r2_object_delete
Delete a single R2 object. Theconfirm: true field is required to prevent accidental deletion.
Parameters
Relative object key, scoped to
R2_ROOT_PREFIX.Must be the literal boolean
true. This field is a required safety guard.Returns
Always
true on success.The relative key of the deleted object.
Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
invalid_path | 400 | Key contains .., null bytes, or is otherwise invalid. |
R2 does not return an error when deleting a key that does not exist. The response will still show
deleted: true.r2_object_delete_many
Delete multiple R2 objects in a single call. UsedryRun: true to preview what would be deleted without actually removing any objects.
Parameters
Array of relative object keys to delete. Minimum 1 key, maximum
MAX_LIST_LIMIT keys (default 100).Must be the literal boolean
true. This field is a required safety guard.When
true, no objects are deleted. The response describes what would have been deleted. Defaults to false.Returns
Live run (dryRun omitted or false):
Array of relative keys that were deleted.
dryRun: true):
Always
true when a dry run was requested.Always
"r2_object_delete_many".The keys that would have been deleted.
Number of keys that would be deleted.
Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
invalid_path | 400 | One or more keys contain .., null bytes, or are otherwise invalid. |
r2_object_copy
Copy a source object to a destination key within the same R2 bucket. The operation reads the source body (subject toMAX_TRANSFER_BYTES) and writes it to the destination, preserving contentType and customMetadata.
Parameters
Relative key of the source object.
Relative key where the copy will be written.
When
false (default), the copy is aborted if the destination already exists. Set to true to overwrite an existing destination.If provided, the copy is aborted when the source object’s ETag does not match this value.
If provided, the destination write is conditional on the current destination ETag matching this value.
Returns
Metadata of the source object at the time of the copy.
Metadata of the newly written destination object.
Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
object_not_found | 404 | Source key does not exist. |
destination_exists | 409 | Destination key exists and allowOverwrite is not true. |
etag_conflict | 409 | expectedSourceEtag or expectedDestinationEtag did not match the stored ETag. |
payload_too_large | 413 | Source object size exceeds MAX_TRANSFER_BYTES. |
r2_object_move
Move a source object to a destination key. This is a copy-then-delete operation and is not atomic. UsedryRun: true to preview the steps without making changes.
Parameters
Relative key of the object to move.
Relative key of the destination.
Must be the literal boolean
true.When
true, an existing destination object will be overwritten. Defaults to false.When
true, no changes are made. Returns a preview of the planned steps.Abort the move if the source ETag does not match this value.
Abort the destination write if the destination ETag does not match this value.
Returns
Live run:The original key that was moved.
The source key that was deleted after the copy.
Metadata of the written destination object.
dryRun: true):
Always
true.Always
"r2_object_move".Source key that would be moved.
Destination key that would be written.
Ordered list of steps that would be executed:
["copy source to destination", "delete source"].Resolved value of
allowOverwrite.Value of
expectedSourceEtag, or null if not supplied.Value of
expectedDestinationEtag, or null if not supplied.Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
object_not_found | 404 | Source key does not exist. |
destination_exists | 409 | Destination exists and allowOverwrite is not true. |
etag_conflict | 409 | Source or destination ETag mismatch. |
payload_too_large | 413 | Source object size exceeds MAX_TRANSFER_BYTES. |
r2_object_rename
Rename an R2 object within its current prefix or move it to an explicittargetPrefix. The new name must be a basename — it cannot contain / or \. Internally delegates to r2_object_move.
Parameters
Relative key of the object to rename.
New basename for the object. Must be at least 1 character, must not contain
/ or \, and must differ from the current basename.Must be the literal boolean
true.Explicit destination prefix. When omitted, the parent prefix of
currentKey is used (the object stays in the same “folder”).When
true, an existing object at the computed destination key will be overwritten. Defaults to false.When
true, no changes are made. Returns a preview of the planned operation.Abort the rename if the source ETag does not match this value.
Abort the destination write if the destination ETag does not match this value.
Returns
Live run:The original key that was renamed.
The source key that was deleted after the copy.
The computed destination key (prefix + newName).
Metadata of the newly written destination object.
dryRun: true):
Always
true.Always
"r2_object_rename".The key that would be renamed.
The new basename.
The resolved target prefix, or
null if defaulting to the current parent prefix.Ordered list of steps:
["copy current key to renamed destination", "delete current key"].Resolved value of
allowOverwrite.Value of
expectedSourceEtag, or null if not supplied.Value of
expectedDestinationEtag, or null if not supplied.Error codes
| Code | HTTP Status | Meaning |
|---|---|---|
no_op_rename | 400 | newName is identical to the current object’s basename. |
invalid_path | 400 | newName contains /, \, null bytes, or is empty after trimming. |
object_not_found | 404 | Source key does not exist. |
destination_exists | 409 | Destination exists and allowOverwrite is not true. |
etag_conflict | 409 | Source or destination ETag mismatch. |
ObjectMetadata type
All metadata-returning tools share this shape.Relative object key, scoped to
R2_ROOT_PREFIX.Object size in bytes.
MIME type stored with the object, or
null if not set.ETag of the stored object.
ISO 8601 UTC timestamp of the last write (
uploaded field from the R2 API), or null if unavailable.Arbitrary string key-value pairs attached to the object. Empty object
{} when none are set.Error Codes
The followingR2McpError codes can be returned by object tools. Each error carries a machine-readable code, an HTTP status, a human-readable message, and optional details.
| Code | HTTP Status | Meaning |
|---|---|---|
object_not_found | 404 | Object key not found in R2. |
unsupported_content_type | 415 | Object content type is not text-like. Use r2_download_base64 for binary objects. |
payload_too_large | 413 | Object or text payload exceeds MAX_INLINE_TEXT_BYTES or MAX_TRANSFER_BYTES. |
etag_conflict | 409 | A conditional write or copy failed because the stored ETag did not match expectedEtag. |
object_already_exists | 409 | r2_object_put_if_absent failed because an object already exists at the key. |
destination_exists | 409 | Copy or move destination already exists and allowOverwrite was not set to true. |
no_op_rename | 400 | The newName supplied to r2_object_rename is identical to the current basename. |
invalid_path | 400 | Key contains .., a leading /, null bytes, or a basename with path separators. |
out_of_scope | 403 | Key falls outside the configured R2_ROOT_PREFIX scope. |