pipefy-attachments

Attachments

Upload one file at a time to a card or table-record attachment field. The upload goes through Pipefy's presigned URL flow (request URL, S3 PUT, then field update). 2 MCP tools, 1 CLI command.

---

When to use

• The user says "attach this file to card X" or "upload to the documents field on record Y".
• The user has a file on their local filesystem (a path like ~/report.pdf or /tmp/export.csv). If the agent has generated bytes that are not yet on disk, write them to a temporary path first and pass the path.

Do not use this skill for:

• Reading or listing existing attachments. There is no list/download tool in this skill scope. Cards and table records expose their attachments through the regular card/record fetch tools.
• Bulk uploads. One file per call; iterate at the agent layer.

Prerequisites

• A Pipefy organization_id. Find it via get_organization or get_pipe.
• A target card_id or table_record_id.
• The attachment field's slug (the human-readable id like document_upload, not the field's uuid). Find it on the card or table record fetch tools.
• A file at a path the MCP server can read. The server runs locally as the user, so any path the user can access is fine.

Tools needed

Tool (MCP)	CLI equivalent	Read-only
upload_attachment_to_card	pipefy attachment upload --card <id>	No
upload_attachment_to_table_record	pipefy attachment upload --record <id>	No

Trust model

The MCP server runs locally as a subprocess of the agent runtime, with the same filesystem access the user already has. There is no separate sandbox. Any path the user can read is a valid file_path. There is no file_url input mode in this distribution; if the agent has a URL, fetch it locally first (e.g. curl -o /tmp/file.pdf <url>) and pass the resulting path.

Steps

Upload a local file to a card

file_name is inferred from the path's basename when omitted, so callers usually only pass the four IDs and the path.

MCP:

upload_attachment_to_card organization_id=42 card_id=1234 field_id=document_upload file_path=~/report.pdf

CLI:

pipefy attachment upload --org 42 --card 1234 --field document_upload --file ~/report.pdf

Upload a local file to a table record

MCP:

upload_attachment_to_table_record organization_id=42 table_record_id=tr-555 field_id=document_upload file_path=/tmp/export.csv

CLI:

pipefy attachment upload --org 42 --record tr-555 --field document_upload --file /tmp/export.csv

Upload bytes the agent generated

Write the bytes to a temporary file first, then pass its path:

upload_attachment_to_card organization_id=42 card_id=1234 field_id=document_upload file_path=/tmp/invoice.pdf

Overriding the file name

When you want the attachment stored in Pipefy under a different name than the local file's basename, pass file_name explicitly. It wins over the path's basename.

upload_attachment_to_card ... file_path=/tmp/abc123.pdf file_name=Invoice-2026.pdf

Success criteria

The tool returns a payload with success: true, a download_url (the signed URL Pipefy returns), the inferred or explicit content_type, and the file_size in bytes. The attachment field on the card or record now lists the uploaded file.

Failure modes

When the tool gets through argument coercion, the failure payload carries a step field. The possible values:

• step=validation. file_path missing or blank. Recovery: pass a non-empty path to the file the MCP server should upload.
• step=file_read. file_path does not exist, points to a directory, is unreadable, has an unknown ~user prefix, or is larger than 100 MiB. Recovery: verify the path exists as a regular file the running user can read and is under the cap.
• step=presigned_url. Organization id rejected, field id not an attachment, or Pipefy refused the request. Recovery: confirm organization_id with get_organization and that the field is actually an attachment field on the target card or record.
• step=s3_upload. The presigned URL expired before PUT, or content/headers did not match what was signed. Recovery: retry the tool to obtain a fresh presigned URL. For unusually large files, expect Pipefy's storage policy to enforce the cap.
• step=field_update. The field rejected the new attachment list (wrong type, missing permission). Recovery: confirm the field accepts attachments and that the caller has write access to the card or record.

If file_path (or any other required argument) is omitted or has the wrong type, the payload uses the standard Pipefy invalid-arguments envelope instead: {"success": false, "error": {"code": "INVALID_ARGUMENTS", "message": "...", "details": {"errors": [...]}}}. Recovery: read error.details.errors[*].path to see which argument failed, then retry.

See also

• skills/pipes-and-cards/pipefy-pipes-and-cards/SKILL.md: finding card ids and attachment field slugs.
• skills/database-tables/pipefy-database-tables/SKILL.md: finding table record ids and field slugs.