How to Design an MCP Image Upload Tool | ATLASSC.NET
Skip to main content
/// .DATA.FRAGMENT_20261122

How to Design an MCP Image Upload Tool

7 minAuthor: Z.SHINCHVEN

Suppose you ask an agent to add a local file called hero.png to your Covers library. The model needs the file path and the destination to decide what to do. A local tool that can read the file can handle the transfer.

Why Base64 in tool arguments is an anti-pattern

An MCP tool that takes an imageBase64 argument can tempt you to build a two-call workflow. First, a local tool reads hero.png, encodes it as Base64, and returns the string to the model. Then the model has to emit that same string in the JSON arguments of the upload tool. The encoded image consumes input and output tokens, can hit context or output limits, and must be copied exactly for the upload to succeed. All that work happens after the model has already decided which file to upload.

Give the model the path and let a tool with filesystem access open it. That tool can be the agent's shell, a script, or a dedicated local uploader. It takes the path and upload URL, sends the file bytes directly to the upload API, and returns a small status result. The path must be readable in the tool's execution environment. A remote MCP server has no inherent access to a path on the user's machine.

The workflow below uses MCP for the operations the model needs to coordinate. create_upload accepts file metadata and returns a one-time URL and an uploadId. A local tool sends the raw bytes to that URL over HTTP. Once the upload is ready, add_files_to_library uses the ID to attach the image to the selected library.

The upload sequence

The local tool can read the file and make HTTP requests. The MCP endpoint and upload API belong to the same application. On a phone, swipe horizontally to see the full sequence.

%%{init: {"sequence": {"actorMargin": 24, "width": 112, "wrap": true}}}%%
sequenceDiagram
    actor U as User
    participant A as Agent
    participant L as Local file tool
    participant M as MCP server
    participant H as Upload API
    participant S as Object storage

    U->>A: Add hero.png to Covers
    A->>L: Read metadata for hero.png
    L-->>A: MIME type and byte count
    A->>M: create_upload (file metadata)
    M-->>A: uploadId and one-time uploadUrl
    A->>L: Upload hero.png to uploadUrl
    L->>H: PUT uploadUrl (raw image bytes)
    Note over H: Claim the upload and validate the file
    H->>S: Store the staged image and variants
    H-->>L: 200 OK, status = ready
    L-->>A: Upload ready
    A->>M: add_files_to_library (library ID and uploadId)
    M-->>A: Preview and confirmationHash
    A->>U: Show the filename and destination
    U-->>A: Approve the addition
    A->>M: Repeat with confirmed and confirmationHash
    M->>S: Copy files to the library path
    Note over M: Create the library item
    M-->>A: New item ID and library link
    A-->>U: Report that the image was added

1. Request an upload URL with create_upload

Use a local tool to get the exact byte count with wc -c < hero.png and the detected MIME type with file -b --mime-type hero.png. Then call create_upload through an authenticated MCP session. This example assumes the file is 48,211 bytes.

{
  "files": [
    { "filename": "hero.png", "mimeType": "image/png", "size": 48211 }
  ]
}

The server checks the declared media type, the per-file size limit, and the account's storage quota. This implementation accepts PNG, JPEG, WebP, and GIF images up to 50 MiB per file. If the checks pass, it creates an account-scoped record with status awaiting_upload.

The tool returns an uploadUrl carrying a single-use credential valid for 15 minutes and an uploadId that identifies the staged record. Use the URL to send the file and keep the ID for status checks and attachment. The result also includes the HTTP method and a ready-to-run curl command. For batch requests, uploads contains the files that received URLs, and rejected explains why the others were refused.

2. Send the image from a local tool

Have the agent's shell run this command where it can read hero.png. Set UPLOAD_URL to the URL returned by create_upload. The --fail-with-body option preserves the server's error response and gives scripts a nonzero exit code on HTTP errors.

curl --fail-with-body -sS -T hero.png "$UPLOAD_URL"

With -T, curl opens the path and sends the file as the raw request body. The agent receives the HTTP result and can continue with the uploadId it already has. The application receives the bytes at a route such as /api/staged-uploads/:id?token=…. The token in the URL authorizes this upload, so the process sending the file can work with that short-lived URL alone. Treat the URL as a credential and redact the token from access logs.

The server stores a hash of the token. After checking the token and its expiry, it conditionally updates the upload from awaiting_upload to processing before reading the body. If two PUT requests arrive together, only one can claim the upload. The server reads the body in chunks, stops once the bytes exceed the declared size, and checks the exact byte count when the body ends.

The server identifies the image format from the file header, checks that the detected media category matches the declaration, and records the detected MIME type. The application buffers the file within the size limit, then uses the same processing pipeline as web uploads to generate thumbnails and optimized versions. Sharing that pipeline keeps the output consistent across both entry points. Concurrent uploads still use application memory.

After the original and its generated variants reach object storage, the endpoint returns 200 OK with status: "ready". If the connection drops before the response arrives, call get_upload with the original uploadId. A ready upload can be attached. For processing, check again later. A failed upload includes an error and requires a new URL before sending the file again.

3. Attach the image using its uploadId

Use list_libraries to find the destination, then call add_files_to_library with its ID and the staged image's uploadId. The title and tags describe the new library item.

{
  "library_id": "<image library ID>",
  "files": [
    { "uploadId": "<staged upload ID>", "title": "Homepage cover", "tags": ["cover"] }
  ]
}

The first call returns a preview and a confirmationHash. Show the user the filename and destination. After they approve, repeat the call with the same arguments plus confirmed: true and the returned confirmationHash. The hash binds the preview to the tool name and normalized arguments. If the library, image, or tags change, request a fresh preview.

On execution, the server looks up the library and upload under the authenticated account. It checks that the upload is ready and unexpired, that its media category matches the library, and that the account has enough space for the copy. It then copies the image and its variants within object storage, creates the library item, and returns the new item ID and a link to the library. The confirmation is tied to the concrete action the user can review, such as adding hero.png to Covers.

Why stage the file first?

Staging lets one upload serve several actions. The same uploadId can add an image to a library, supply an input to a project workflow, or attach media to a draft post. A staged upload is available for 24 hours from creation. Its files count toward the storage quota until cleanup removes them. Library items have their own copies, so they remain available after the staged objects expire.

Each destination can use the same service to receive and validate files. Its MCP tool only needs to resolve the uploadId, verify ownership and readiness, and apply the rules for that destination. The client can recover the state of the transfer even if it has yet to choose where the image belongs.

References

RackNerd Billboard Banner
Share node:
/// .RELATED.DATA_STREAMSShared tags

Related posts

Scanning_database_for_correlations…

/// .UPLINK.SUBSCRIBE

Keep your deck synced with every new transmission from ATLASSC.NET. Subscribe over RSS or Atom, or wire the whole archive straight into your AI assistant with the MCP server.