File Tools

MCP tools for querying uploaded files and their processing status

File Tools

Query uploaded files — invoices, spreadsheets, and documents — along with their processing status and linked facilities. Files are the entry point for bulk data imports (purchases, invoices, employees, etc.).

list_files

List uploaded files with optional filters by name, extension, status, or date range.

Parameters:

Parameter	Type	Required	Default	Description
organization_id	string	No	default org	Organization UUID
name	string	No	—	Filter by file name (partial match)
extension	string	No	—	Filter by extension: pdf, xlsx, csv, etc.
status	string	No	—	Processing status: pending, uploaded, error, deleted
from_date	string	No	—	Filter from upload date (YYYY-MM-DD)
to_date	string	No	—	Filter until upload date (YYYY-MM-DD)
page	integer	No	1	Page number
size	integer	No	50	Results per page

Example response:

{
  "items": [
    {
      "id": "f3a1b2c4-...",
      "name": "invoices_q1_2025.xlsx",
      "extension": "xlsx",
      "mime_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
      "size_kb": 245,
      "status": "uploaded",
      "url": "https://storage.dcycle.io/...",
      "tags": ["invoices", "q1"],
      "organization_id": "a1b2c3d4-...",
      "folder_id": "d4c3b2a1-...",
      "linked_facilities": [
        { "id": "4cc2ac22-...", "name": "Madrid Office" }
      ],
      "linked_projects": [],
      "reading_status": "success",
      "current_step": null,
      "created_at": "2025-03-15T09:20:00"
    }
  ],
  "total": 128,
  "page": 1,
  "size": 50,
  "pages": 3
}

Key response fields:

Field	Description
status	pending (uploading), uploaded (ready/processed), error (failed), deleted
extension	File type: pdf, xlsx, csv, xml, etc.
size_kb	File size in kilobytes
linked_facilities	Facilities linked via invoice/waste data in the file
reading_status	AI reading status for invoices: success or error (null if not read)
current_step	Current ingestion step (null if not actively being processed)
tags	User-assigned labels

get_file

Get detailed information about a specific file by ID.

Parameters:

Parameter	Type	Required	Default	Description
file_id	string	Yes	—	UUID of the file
organization_id	string	No	default org	Organization UUID

Example prompts:

"List all PDF files uploaded this month"
"Show me files with errors"
"What files were uploaded for our Madrid office?"
"List CSV files from last week"
"What's the processing status of file abc-123?"
"Show recently uploaded invoices"

Workflow

1. List files — list_files to find uploaded files by name, type, or status
2. Check details — get_file for a specific file’s processing state
3. Check processing — list_processing_jobs to see if a file upload triggered calculations and their status
4. View imported data — Use the corresponding data tool (e.g. list_invoices, list_purchases) to see records created from the file

Related

Processing Jobs

Track file upload processing and calculation status

Invoices

Invoice data often imported via file uploads

API Reference

REST API endpoints for file management

CLI

Upload and manage files from the command line