Hosted-safe attachment path

[gbrlcustodio]

Part of the hosted on-behalf-of MCP server proposal (#297).

Scope

Provide an attachment-upload path that does not depend on the server's local filesystem: a client-supplied file URL with SSRF and size guards, an in-body upload, or a client-side presigned upload. Gate the local-file-path variant to the stdio profile.

Acceptance criteria

An attachment can be uploaded in the hosted profile without server filesystem access; the local-file-path variant is unreachable in the hosted profile; the tool is then marked remote-safe.

Dependencies

Depends on the default-deny allowlist (#304).

[adriannoes]

Field report: the same gap bites the stdio profile through claude.ai connectors

A user hit this with the local stdio server, so the problem is not exclusive to the hosted profile. Setup: claude.ai in the browser with code execution enabled, plus the Pipefy MCP connector running on the user's Windows machine. The agent generated a file inside its Anthropic-hosted sandbox (/mnt/user-data/outputs/...) and had no way to hand the bytes to the server. Reproducing that call shape against a path the server cannot see returns:

{"success":false,"error":{"message":"File not found or not a regular file: /mnt/user-data/outputs/felipe-repro.txt"},"step":"file_read"}

The agent then tried base64 input (dropped in 6007155 along with the URL mode; #253's text said base64 would stay as the in-memory fallback, but the final refactor removed it too) and a Google Drive URL (dropped in #253), and ended up asking the user to download the file from the chat and reply with a local path. That works, but it costs several turns and a manual step per file.

The acceptance criterion "an attachment can be uploaded without server filesystem access" therefore needs to hold for two topologies, not one:

1. Hosted profile (the original scope here).
2. Local stdio server whose MCP client is not co-located with the environment that generates files (claude.ai + connector).

What we verified (2026-07-02)

The client-side presigned flow already works with existing tools. Ran end to end against the PipeClaw test org (302398434), card 1406588268, field egress_test_attachment:

1. execute_graphql with createPresignedUrl (organizationId, fileName, contentType) returns the S3 PUT url and a download url.
2. curl -X PUT --upload-file ... to the presigned url: HTTP 200.
3. update_card_field accepts the raw storage path (the url's path component without the leading slash, orgs/<uuid>/uploads/<uuid>/<file>).
4. get_card shows the attachment. The signed download url is minted on read, not stored, so clients never construct download urls.

Constraints observed: the presigned url carries X-Amz-Expires=300, so mint and PUT must happen within 5 minutes. Upload host: pipefy-prd-us-east-1.s3.amazonaws.com.

But the claude.ai code-execution sandbox cannot reach that host by default. Probes from inside the sandbox (Linux, transparent egress interception, no proxy env vars):

Host	Result
pipefy-prd-us-east-1.s3.amazonaws.com	403 Host not in allowlist from the egress gateway
app.pipefy.com	blocked, same gateway message
api.pipefy.com	blocked, same gateway message
pypi.org (control)	200

The default allowlist covers package managers and api.anthropic.com only. The gateway message says an org owner can add hosts under the workspace's network egress settings, so the presigned path is viable for orgs that allowlist the upload host, but it is not a default-config solution. The block fires on host before method, so PUT traversal after allowlisting is still unverified (expected to pass, since filtering is per host).

Implications for the design

• A client-supplied file_url does not solve the claude.ai sandbox case: sandbox files are not at fetchable urls. It stays useful for the hosted profile when the client genuinely holds a url.
• file_content_base64 is the only input mode that works in every topology (no server filesystem read, no sandbox egress needed): the bytes ride the tool call itself. The practical cap is small, roughly 1 to 2 MiB decoded, because the argument passes through the model's context, but that covers the reported case (generated specs, CSVs, small reports). It reads no filesystem and downloads nothing, so it qualifies for meta=REMOTE immediately. The pre-6007155c implementation is a starting point.
• The client-side presigned recipe deserves documentation (skill and tool docs) as the large-file escape hatch for orgs that allowlist the upload host. It needs no new tool today, though a dedicated create_attachment_presigned_url tool would remove the dependency on execute_graphql (which a hosted profile is unlikely to expose) and could itself be marked remote-safe.
• Two cheap fixes for the failure mode itself, independent of the input-mode work:
  • The file_read error message should say the path must exist on the machine running the MCP server, which may not be the agent's own environment. The current message gave the agent no hint; it burned several turns rediscovering the topology on its own.
  • skills/attachments/pipefy-attachments/SKILL.md states "There is no separate sandbox" and tells agents to write generated bytes to a temp path and pass the path, which is exactly the failing move in this topology. It needs a decision path: file on the user's disk, use file_path; agent-generated file in a separate sandbox, use base64 when small, otherwise artifact download plus user-supplied path (or the presigned flow when egress allows).

Test fixtures kept for follow-up work: PipeClaw org 302398434, pipe SandboxTestes 307078102, attachment field slug egress_test_attachment, card 1406588268.