Skip to main content
When an MCP tool declares an input field with format: "file", Langdock intercepts the LLM’s file reference and resolves it into a structured FileData object before the MCP server receives the call.

How It Works

When a user attaches a file in chat and the LLM references it (as a filename like report.pdf, a storage path like attachment/<uuid>/<filename>, or /mnt/data/<filename>), Langdock’s engine intercepts that reference and resolves it into a full FileData object before passing it to your MCP tool. Knowledge files from an agent with source access restriction are the exception. Langdock stops the call before downloading the file, so your tool never receives it.

The FileData Shape

Your MCP tool receives the following object:

The .meta({ format: "file" }) Marker

The key signal to Langdock is adding .meta({ format: "file" }) to your Zod schema field. When you save the MCP integration, Langdock detects format: "file" in the JSON schema and stores the field as a FILE type. At execution time, Langdock resolves the file reference into a full FileData object and passes it to your MCP server.

Implementing File Input in Your MCP Server

Declare the input field as a Zod object matching the FileData shape. Do not use z.string() — the MCP SDK validates inputs before calling the handler, so the schema must match what it actually receives:

Example Tool Input and Output

When Langdock calls your tool, it sends a fully resolved FileData object:
Your tool can then return metadata or processed results:

Example Project

The langdock_mcp_file_upload repository is a minimal working MCP server that demonstrates the full file input flow — from schema declaration to handling the resolved FileData in the tool handler.

FAQ

Use file input when the external MCP tool needs to inspect or process a file that the user references in Langdock. This is useful for tools that parse, transform, validate, or upload files to another system.
Check that the MCP tool declares a file input field, the user referenced an available file, the file type is supported by the tool, and the tool handles the file data format Langdock sends. If the file is knowledge from an agent with source access restriction, Langdock blocks the call and your tool isn’t called.