Skip to main content

Drag & Drop Files

When the user drag-drops a PDF (or any supported file) into a chat-style MCP host such as Claude Desktop, Cowork, or Cursor, the file lands in a host-owned sandbox directory the MCP server cannot read. The path the host hands the agent is meaningless to a separately-running npx MCP process.

@talonic/mcp@0.1.4 and later solve this by accepting `file_data` (base64-encoded file bytes) and `filename` on talonic_extract and talonic_to_markdown. The agent reads the file bytes from the conversation, base64-encodes them, and passes them through the MCP tool call. The MCP server decodes, infers MIME type from the filename, and uploads to the Talonic API.

This approach works transparently across all chat-style MCP clients. The agent does not need to know where the file is stored on disk, and the user does not need to configure file paths or directory permissions. The entire flow — from drop to structured extraction — happens in a single conversation turn.

Supported file types include PDF, PNG, JPG, TIFF, DOCX, XLSX, and other common document formats. The MCP server infers the MIME type from the filename extension, so always include the original file extension when passing file_data. If the extension is missing or unusual, the server may reject the upload with an unsupported_file_type error.

Example: drag-and-drop extraction flow

What the agent sends when a user drops a PDF
// User drops "receipt-2026-05.pdf" into the chat
// The MCP client base64-encodes the file bytes automatically
// Agent calls talonic_extract:
{
  "file_data": "JVBERi0xLjQKJcOkw7zDtsO8...",
  "filename": "receipt-2026-05.pdf",
  "schema": {
    "type": "object",
    "properties": {
      "merchant": { "type": "string" },
      "date": { "type": "string", "format": "date" },
      "total": { "type": "number" },
      "payment_method": { "type": "string" }
    },
    "required": ["merchant", "total"]
  }
}
Extraction response from dropped file
{
  "status": "complete",
  "document": {
    "id": "doc_f1e2...",
    "filename": "receipt-2026-05.pdf",
    "pages": 1,
    "type_detected": "receipt"
  },
  "data": {
    "merchant": "Coffee House Berlin",
    "date": "2026-05-07",
    "total": 14.80,
    "payment_method": "Visa ending 4242"
  },
  "confidence": { "overall": 0.95 }
}

The drag-and-drop flow works identically across Claude Desktop, Cowork, and other chat-style MCP clients that support file attachments. The key requirement is that the client encodes the file as base64 and passes it in the file_data parameter alongside the original filename. The MCP server uses the filename extension to determine the MIME type, decodes the base64 bytes, and uploads the file to the Talonic API in a single request.

For large files (over 10 MB), the base64 encoding increases the payload size by approximately 33%. Most MCP clients handle this transparently, but some hosted connectors (notably Claude.ai's web connector) have payload size limits that can truncate the encoded data. If you encounter issues with large files in a hosted connector, use file_url with a publicly reachable URL or upload the document through the Talonic dashboard and reference it by document_id instead.

Tool descriptions advertise file_data as the recommended input for chat-style clients, so well-trained agents reach for it automatically. No client-side configuration required.

Frequently asked questions

Can I drag and drop files into Claude Desktop with Talonic?+
Yes. Since @talonic/mcp@0.1.4, talonic_extract and talonic_to_markdown accept base64 file data directly, so you can drop a PDF into Claude Desktop and extract data without file path setup.
What file types can I drag and drop?+
PDF, PNG, JPG, TIFF, DOCX, XLSX, and other common document formats. The MCP server infers the MIME type from the filename extension.
Why does drag-and-drop fail with an unsupported_file_type error?+
The filename is missing a recognisable extension. Make sure the original filename with its extension is passed in the filename parameter alongside file_data.
What happens if the dropped file is too large?+
Base64 encoding increases payload size by about 33%. Most local MCP clients handle this fine, but hosted connectors may have payload limits. For large files (over 10 MB), use file_url with a public URL or upload via the Talonic dashboard and reference by document_id instead.
Do I need to configure anything for drag-and-drop to work?+
No. The file_data parameter is advertised in the tool descriptions, so MCP clients that support file attachments automatically encode and pass the file. Just drop the file into the chat and provide a schema — the agent handles the rest.

Related

talonic_extract
talonic_to_markdown
Common Issues