Attachment Tool (MCP_ATTACHMENT_TOOL)

Lets an agent read a file that a user attached to a message in the agent chat.

Category: none (see Adding it to a pipeline) · Deployed: yes · Tool-capable: yes (only)

Why you need it

An agent does not read attached files by itself. When a user attaches a file, the agent server keeps the file. The model only gets a short list under the user’s message: the file name, the file type and an attachment ID. The content is not part of it.

The Attachment Tool is the only way to get at the content. When the model calls it with an attachment ID, the agent server sends the file to one function (tool) on an external tool server (MCP server). That server turns the file into something the model can use, for example text. The agent gets this answer back and can work with it.

Example: a user attaches a contract as a PDF and asks "When does this contract end?". The agent calls the Attachment Tool. The tool sends the PDF to a document conversion server, which returns the text of the contract. The agent reads the end date from that text and answers.

Without an Attachment Tool, the agent knows that a file was attached, but it cannot open it. No error is shown — the agent simply cannot answer questions about the content.

Ports

Port Kind Purpose

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port. This is the module’s only connection

A typical chat pipeline: Chat Input → Agent → Chat Output, and the Attachment Tool connected to the Agent’s Tools port.

Properties

Field Required Meaning

URL (url)

Yes

The address of the tool server that reads the file, for example docling:5001/sse. The agent server must be able to reach this address

Tool Name (toolName)

Yes

The function to call on that server, written exactly as the server names it — for example convert_document or transcribe_image. A wrong name is not found when you save. It fails only when the agent uses the tool

Description (description)

No

Tells the agent which files this tool can read and when to use it. A clear text → the agent uses the tool when it should. Empty → a general text that only names the tool and says to call it with the attachment ID

Argument names

The tool server decides what its inputs are called. These fields tell the Attachment Tool which names to use. Change them only if the server’s documentation uses other names.

Field Default Meaning

Content Argument (contentArgName)

content

The name for the file content. The content is always sent. An empty field uses content

Send the file name (checkbox)

On

On → the original file name is sent. Some servers need it to recognise the format (for example .pdf). Off → no file name is sent at all

Filename Argument (filenameArgName)

filename

The name for the file name. An empty field uses filename. Only used while Send the file name is on

Send the file type (checkbox)

On

On → the file type is sent, for example application/pdf. Off → no file type is sent at all

MIME Type Argument (mimeTypeArgName)

mimeType

The name for the file type. An empty field uses mimeType. Only used while Send the file type is on

Switch a checkbox off only if the server rejects an input it does not know. An empty name field is not the same as a cleared checkbox: an empty field sends the input under its default name, a cleared checkbox does not send it at all.

What the tool server receives

For each call, the agent server calls the configured function once, with these inputs:

Input (default name) Value

content

The whole file, encoded as text (Base64). This makes it about one third larger than the file

filename

The file name as the user attached it. Left out when Send the file name is off

mimeType

The file type. If the browser did not send a specific type, it is derived from the file name extension. Left out when Send the file type is off

The answer of the tool server goes back to the agent unchanged. The model never gets the file itself, only this answer.

Before you start: the agent’s settings

The pipeline alone is not enough. On the agent’s Configuration tab, under Chat Attachments (see Agent Server):

  • File types. Tick the kinds of files users may attach: Text files, Documents or Images. With nothing ticked (the default for a new agent), the chat shows no attach button at all. Tick only types that your tool server can read.

  • Largest Chat Attachment (MB) — the largest file a user can attach to one message, from 1 to 25 MB. Default: 10. Higher → bigger files reach the Attachment Tool. Lower → bigger files are refused right away with a message. A change applies after the agent is restarted.

Use cases

  • Questions about a document: a document conversion server (for example Docling) turns a PDF, DOCX, XLSX or PPTX file into text, and the agent answers from it.

  • Reading pictures: a server that describes or transcribes images, for example a scanned receipt.

  • Several file kinds: connect two Attachment Tools to the same Agent — one for documents, one for images — and say in each Description which files it is for. The agent then picks the right one.

Adding it to a pipeline

The palette of the Pipeline Designer currently has no entry for the Attachment Tool. You can only work with it in pipelines that already contain one, for example a pipeline that was imported with it. There you can edit its properties and connect it like any other module.

Notes

  • A file is available only for the message it was attached to. The agent server deletes it when the answer to that message is finished, and after 15 minutes at the latest. If the user asks about the file in a later message, the agent cannot open it any more — attach it again.

  • The URL must work from inside the agent server’s container. localhost there means the agent server itself, not your computer.

  • Tool Name must match exactly, including upper and lower case. A wrong name fails only when the agent uses the tool: the tool server "does not expose a tool named …".

  • Write a Description. Name the file types the tool can read, for example "Reads PDF and Word files the user attached. Use it whenever the user asks about an attached document." This helps the agent call it at the right time.

  • The Agent’s model must be able to use tools. A model that cannot call tools never uses the Attachment Tool.

Troubleshooting

What you see Likely cause

No attach button in the chat

No file type is ticked under Chat Attachments on the agent

A file is refused as too large

It is larger than Largest Chat Attachment (MB) on the agent

The agent says it cannot open or read the file

The pipeline has no Attachment Tool, or it is not connected to the Agent’s Tools port

The tool call fails with "does not expose a tool named …"

Tool Name does not match the function name on the tool server

The tool call fails with "no attachment found …"

The file was attached to an earlier message, or more than 15 minutes have passed. Attach it again

The tool server reports a missing or unknown input

The argument names do not match the server. Check the server’s documentation and adjust the names or the Send … checkboxes

The tool call fails because the server cannot be reached

Wrong URL, or the address does not work from inside the agent server’s container