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

// 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"]
  }
}

{
  "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.

This file_data path works without limit in local-stdio installs (Claude Desktop, Cursor, Cline, Continue, Cowork). It does not work in the Claude.ai hosted connector, which caps tool-call arguments at ~32 KB decoded (~43 KB base64, measured against production) — a real PDF is silently truncated. In hosted connectors, use `talonic_request_upload`: it returns a browser link (https://app.talonic.com/u/<token>) the user opens to drop the file, after which the agent polls talonic_get_document until status is completed and then calls talonic_extract by document_id. file_url (a publicly reachable URL) and a pre-uploaded document_id also work.