Gmail upload attachment

gmail__upload_attachment

Use this instead of returning Gmail attachment bytes through model/tool context.

Access

Requires a project integration connection for gmail.

Call type: Can change resources.

Arguments

FieldTypeRequiredDescription and constraints
project_referencestringNoProject ID or slug
message_idstringYesGmail message ID containing the attachment. Minimum length: 1.
attachment_idstringYesGmail attachment ID from the message payload part body. Minimum length: 1.
file_pathstringYesDestination upload path (e.g., gmail-proof/originals/invoice.pdf). Raw JSON path; spaces, Unicode and literal percent characters are accepted. Do not URL-encode.
content_typestringNoMIME type to store with the upload. Defaults to application/octet-stream because Gmail attachment bodies do not include content type. Minimum length: 1.
expected_sizeintegerNoOptional exact decoded byte size guard. The tool fails if decoded bytes do not match.
max_bytesintegerNoOptional decoded attachment size limit in bytes. Defaults to 104857600 and is capped at 536870912. Maximum: 536870912.

Example request

Send this JSON-RPC request through an initialized MCP client. Replace sample identifiers and values before calling the tool. See MCP client setup.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gmail__upload_attachment",
    "arguments": {
      "message_id": "example",
      "attachment_id": "example",
      "file_path": "example"
    }
  }
}

Result

The published output shape is summarized below. Inspect both the MCP response content and isError when handling a call.

FieldTypeRequiredDescription and constraints
upload_idstringYesPersisted upload UUID. Format: uuid.
file_pathstringYesStorage path including the project id prefix. Prefer path when chaining upload tools. get_upload_download_url also accepts this legacy value within the same project.
pathstringYesPath relative to the project root, without the project id. Pass this path value as the upload_reference of get_upload_download_url and as the path of the other upload tools.
file_namestringYesFilename from the stored project-relative path.
content_typestringYesEffective stored MIME type; application/octet-stream when unavailable. Minimum length: 1.
sizeintegerYesActual stored byte size, including zero. Reused uploads retain their stored size; fresh downloads obey the tool byte limit. Minimum: 0. Maximum: 9007199254740991.
statusstringYesPersisted upload status returned by the storage record, normally active.

Full schemas

json
{
  "type": "object",
  "properties": {
    "project_reference": {
      "type": "string",
      "description": "Project ID or slug"
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "description": "Gmail message ID containing the attachment."
    },
    "attachment_id": {
      "type": "string",
      "minLength": 1,
      "description": "Gmail attachment ID from the message payload part body."
    },
    "file_path": {
      "type": "string",
      "description": "Destination upload path (e.g., gmail-proof/originals/invoice.pdf). Raw JSON path; spaces, Unicode and literal percent characters are accepted. Do not URL-encode."
    },
    "content_type": {
      "type": "string",
      "minLength": 1,
      "description": "MIME type to store with the upload. Defaults to application/octet-stream because Gmail attachment bodies do not include content type."
    },
    "expected_size": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Optional exact decoded byte size guard. The tool fails if decoded bytes do not match."
    },
    "max_bytes": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 536870912,
      "description": "Optional decoded attachment size limit in bytes. Defaults to 104857600 and is capped at 536870912."
    }
  },
  "required": [
    "message_id",
    "attachment_id",
    "file_path"
  ],
  "additionalProperties": false,
  "description": "Arguments for the gmail__upload_attachment tool.",
  "$schema": "http://json-schema.org/draft-07/schema#"
}
json
{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "format": "uuid",
      "description": "Persisted upload UUID."
    },
    "file_path": {
      "type": "string",
      "description": "Storage path including the project id prefix. Prefer `path` when chaining upload tools. `get_upload_download_url` also accepts this legacy value within the same project."
    },
    "path": {
      "type": "string",
      "description": "Path relative to the project root, without the project id. Pass this `path` value as the `upload_reference` of `get_upload_download_url` and as the path of the other upload tools."
    },
    "file_name": {
      "type": "string",
      "description": "Filename from the stored project-relative path."
    },
    "content_type": {
      "type": "string",
      "minLength": 1,
      "description": "Effective stored MIME type; application/octet-stream when unavailable."
    },
    "size": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Actual stored byte size, including zero. Reused uploads retain their stored size; fresh downloads obey the tool byte limit."
    },
    "status": {
      "type": "string",
      "description": "Persisted upload status returned by the storage record, normally active."
    }
  },
  "required": [
    "upload_id",
    "file_path",
    "path",
    "file_name",
    "content_type",
    "size",
    "status"
  ],
  "additionalProperties": false,
  "description": "Structured download url to project upload output schema for MCP tools.",
  "$schema": "http://json-schema.org/draft-07/schema#"
}