# Tools reference Source: https://docs.file.ai/mcp/tools > Every tool the fileAI MCP server exposes, with its parameters. MCP server # Tools reference Copy pageCopy page Every tool the fileAI MCP server exposes, with its parameters. Copy pageCopy page The fileAI MCP server exposes 31 tools. Each one calls the fileAI API on the instance your connection points at: as you when you signed in, or with the key’s project access when you connect with an API key (see [How you connect](/mcp/overview#how-you-connect)). Your assistant picks the tool and fills in the parameters; this page tells you what each tool can do so you know what to ask for. ## [​ ](#parameters-every-tool-shares) Parameters every tool shares * **`project_id`** (string, optional): the project to work in, as a 24-character id from [`list_projects`](#account-and-projects). Required when you connected by signing in to fileAI (Claude). If it’s left out, the tool replies with the list of projects so your assistant can ask you which one to use. If the project isn’t in your connection, the tool replies with the projects you can reach and how to add it. Ignored when you connect with an API key, because the key already belongs to one project. Every tool except `list_projects` accepts it. See [Choosing a project](/mcp/overview#choosing-a-project). * **`confirm`** (`true`, required): only on destructive tools: `delete_files`, `delete_directory`, `delete_file_types` and `delete_forensics_run`. The call is rejected unless it is exactly `true`. * **Pagination**: list tools marked _paginated_ also accept `page` (integer), `limit` (integer), `sortBy` (string), `sortOrder` (`ASC` or `DESC`) and `cursor` (string, from the previous response). See [Pagination](/api/pagination). Ids that go into a URL path (`fileId`, `uploadId`, `workflowId`, `directoryId`, `run_id`, `analysis_id`) accept only letters, digits, `_` and `-`. ## [​ ](#account-and-projects) Account and projects Tool What it does Parameters `whoami` Shows which fileAI account the connection uses: the API key name, the project and workspace (ids and names), the plan and the environment. Useful when a file you expect isn’t there, or to check where uploads will go. — `list_projects` Lists the projects you can work in, with their workspace. `truncated: true` in the result means more exist. `search` (string, optional, up to 100 chars — name contains) · `limit` (integer 1–200, optional, default 100) ## [​ ](#files-and-uploads) Files and uploads Tool What it does Parameters `list_files` Lists files, optionally filtered. _Paginated._ `fileIds` (string, optional — comma-separated) · `directoryId` (string, optional) · `updatedAfter` (string, optional — ISO 8601) · `createdAfter` (string, optional — ISO 8601) `get_file_ocr` Returns the OCR text of a file. `fileId` (string, required) `upload_file` Uploads one file in a single call and returns its `uploadId`. `sourceUrl` (string — a public `https` link to the file, up to 50 MB) or `contentBase64` (string — the file’s bytes in base64, up to 10 MB); send exactly one · `fileName` (string, optional — taken from the link, or `file` plus the detected extension) · `fileType` (string, optional — MIME type, detected when omitted) · the same upload options as `request_file_upload`, except `pageCount` `request_file_upload` Returns a presigned URL to upload one file, plus `uploadId` and `s3Path`. It does not transfer the file. `fileName` (string, required) · `fileType` (string, required — MIME type) · `directoryId` (string, optional) · `destinationPath` (string, optional — slash-delimited, folders are created) · `isSplit`, `isSplitExcel`, `schemaLocking`, `isEphemeral`, `retainOriginalZipFileName` (boolean, optional) · `ocrModel` (string, optional) · `pageCount` (integer, optional) · `callbackURL` (string, optional) `wait_for_upload` Waits for an upload to finish processing, checking every 5 seconds, and returns its status: `processed`, `action_required`, `failed`, `processing` or `uploading`. If it’s still running when time is up, `done` is `false`; call it again. `uploadId` (string, required) · `timeoutSeconds` (integer 0–50, optional, default 50; `0` checks once) · `detail` (`summary` or `full`, optional, default `summary`; `full` returns the whole upload record with step-by-step progress and error reasons) `create_file_preview` Returns a short-lived preview URL for a stored file. `s3Path` (string, required — from `upload_file` or `request_file_upload`) `update_file_export_status` Sets a file’s export status as reported by an integrated system. `fileId` (string, required) · `integrationExportStatus` (`error`, `completed`, `exporting` or `empty`, required) · `integrationExportMessages` (string array, optional) `delete_files` Deletes files. Soft-deletes (recoverable) by default. `fileIds` (string array, required) · `isHardDelete` (boolean, optional, default `false`) · `confirm` `delete_files` with `isHardDelete: true` deletes files permanently. ### [​ ](#uploading-a-file) Uploading a file 1 Upload the file Call `upload_file` with either `sourceUrl`, a public `https` link to the file (up to 50 MB), or `contentBase64`, the file’s bytes in base64 (up to 10 MB). The MCP server downloads the link, or decodes the bytes, and stores the file in fileAI for you, so these bytes do pass through the server. The link must point to the file itself: a share page (such as Google Drive or OneDrive) returns a web page and is rejected. Links to private or internal addresses are blocked. 2 Wait for processing Call `wait_for_upload` with the `uploadId` until `status` is `processed`, `action_required` or `failed`. 3 Read the results Call `get_file_values` and `get_file_ocr` for each `fileId` in the result. Values exist only once processing has finished. If your client can send an HTTP `PUT` itself, for example an agent that can run `curl`, it can use `request_file_upload` instead: call it with `fileName` and `fileType`, `PUT` the raw file to the returned `presignedUploadURL` within 5 minutes (the URL is already signed, so don’t add `x-api-key`), then call `wait_for_upload`. Those bytes go straight to fileAI storage and don’t pass through the MCP server. In Claude, a `PUT` from the code sandbox needs network access to your instance’s storage domain. See [Claude: file uploads](/mcp/claude#file-uploads). ## [​ ](#values-and-schemas) Values and schemas Tool What it does Parameters `get_file_values` Returns the extracted values for a file. By default it returns a compact view: each field’s title and value, tables as `columns` and `rows` (first 100 rows), and the `id` that `update_file_values` needs. _Paginated._ `fileId` (string, required) · `view` (`compact` or `full`, optional, default `compact`) · `confirmFullView` (boolean, optional) · `includeFullTableData` (boolean, optional, default `false` — every table row instead of the first 100) `update_file_values` Updates extracted values: scalar fields, table cells, or both. `fileId` (string, required) · `schemaValueId` (string, required — the `id` from `get_file_values`) · `fieldPaths` (array, required — each item has `path` plus either `value` (string) or `cells` (array of `rowIndex`, `column`, `value`), not both) `rerun_form_filling` Re-runs extraction for a file, optionally for specific fields. `fileId` (string, required) · `backgroundRerun` (boolean, optional) · `rerunOptions` (object, optional — `paths` (string array, e.g. `["/discount_amount"]`), `partialRerun`, `notification`) `list_schemas` Lists AI schemas. _Paginated._ `schemaIds` (string, optional — comma-separated) · `uploadIds` (string, optional — comma-separated) `export_schemas` Exports one or more schemas by id. Import is not available. `aiSchemaIds` (string, required — comma-separated) The full `get_file_values` view adds every field definition, citations and validation reasoning, often tens of thousands of tokens. The compact result estimates its size. Your assistant should tell you the cost and ask before it calls again with `view: "full"` and `confirmFullView: true`. ## [​ ](#file-types) File types A file type is the kind of document, such as Invoice or Bank statement, that an AI Schema belongs to. The API calls it a blueprint, so tool parameters use `blueprintId`. See [Concepts](/concepts). Tool What it does Parameters `list_file_types` Lists the file types in the workspace. _Paginated._ — `get_file_type_schemas` Returns the schemas that belong to a file type. _Paginated._ `blueprintId` (string, required) · `blueprintMode` (string, optional) `update_file_type` Approves a file type against a schema (**Verify** in the app), or renames it. `action` (`approve` or `rename`, required) · `blueprintId` (string, required) · `schemaId` (string, required for `approve`) · `name` (string, required for `rename`) `delete_file_types` Deletes file types by id. `blueprintIds` (string array, required) · `confirm` ## [​ ](#folders) Folders Tool What it does Parameters `list_directories` Lists folders, optionally by name. _Paginated._ `search` (string, optional — case-insensitive) `create_directory` Creates a folder. `name` (string, required) · `description` (string, optional) · `parentId` (string, optional — to nest it) · `isActive` (boolean, optional) `manage_directory_documents` Changes which files are in a folder. `attach` adds existing files (ids you can’t see come back under `rejected`). `remove` takes files out of the folder; they stay in the workspace and in any other folders. `move` takes them out and adds them to `targetDirectoryId`. No action deletes a file. `action` (`attach`, `remove` or `move`, required) · `directoryId` (string, required — the source folder for `move`) · `fileIds` (string array, required) · `targetDirectoryId` (string, required for `move`) `delete_directory` Deletes a folder. Files inside are not deleted. `directoryId` (string, required) · `confirm` ## [​ ](#forensics) Forensics fileForensics checks a stored file for signs of editing, AI generation, reuse and hidden content. See [fileForensics](/forensics/overview) for what it does and [Detectors](/verify/forensics#detectors) for what each check looks for. Tool What it does Parameters `run_file_forensics` Starts a fileForensics run on a stored file and returns an `analysis_id`, which is the run’s id. `file_id` (string, required, from `list_files`) · `checks` (string array, optional; omit to run every key below) · `idempotency_key` (string, optional; reuse it when retrying the same request. It usually stops a second run, but isn’t guaranteed: a retry that reaches another server instance, or comes after a restart, can start a new run) `get_file_forensics_result` Returns the run’s status and its report in every state (queued, running, `complete` or `error`); the findings are filled in once it is `complete`. Asking again does not re-run it. By default the report is compact: each check’s status and verdict, without the nested `file_checks` detail. `analysis_id` (string, required) · `view` (`compact` or `full`, optional, default `compact`) · `confirmFullView` (boolean, optional; set `true` with `view: "full"` to get the full report) `retry_forensics` Re-runs a stuck run with the same file and checks, and returns a **new** `run_id`. Use the new id from then on. The new run wasn’t started by `run_file_forensics`, so its results show `billing` as `not_billed`, “not started through this connector”. `run_id` (string, required: the `analysis_id`) `delete_forensics_run` Deletes a run. The file is not affected. `run_id` (string, required: the `analysis_id`) · `confirm` Accepted `checks` values: `web_presence`, `ai_gen_detection`, `ai_text_detection`, `copy_move`, `exact_duplicate`, `provenance_credentials`, `generation_toolchain`, `producer_divergence`, `encryption_permissions`, `active_content`, `digital_signature`, `attachments`, `revision_history`, `magic_byte`, `polyglot`, `trailing_data`, `entropy`, `ai_pdf_detection`, `ai_office_detection`, `heatmap` and `document_integrity_decisions`, plus `layout_parse`, a separate layout parse. `document_integrity_decisions` runs only when it is enabled; otherwise it reports `skip` with “disabled”. Every run also reports the 18 [file checks](/verify/forensics#file-checks). See [Detectors](/verify/forensics#detectors) for what each key does. Results also carry a `billing` field. It is a placeholder: don’t rely on it to track usage or cost. ## [​ ](#workflows) Workflows Tool What it does Parameters `get_workflow` Returns a workflow by id. `workflowId` (string, required) `get_workflow_result_groups` Returns workflow results grouped by folder or subfolder. `executionGroupUniqueIdentifiers` (string, required — comma-separated folder or subfolder ids) · `workflowStepIds` (string, optional — comma-separated) ## [​ ](#workspace) Workspace Tool What it does Parameters `get_project_settings` Returns the project settings. — `get_subscription` Returns the workspace subscription. — ## [​ ](#guided-prompts) Guided prompts The server also offers ready-made prompts, which most clients show as slash commands: `show_file_values`, `validate_document`, `summarize_folder`, `project_inventory` and `find_duplicates` for extracted data, and `check_ai_generated`, `check_tampering`, `verify_authenticity`, `screen_safety`, `check_duplicate` and `full_forensic_audit` for fileForensics. Each one runs the right tools for that task. ## [​ ](#limits-and-errors) Limits and errors * **Long results are cut.** A tool result over 100,000 characters is cut off and ends with `[truncated: N chars total, use pagination or narrower filters]`. This mostly affects `get_file_values` with `includeFullTableData: true` or `view: "full"`, and `get_file_ocr` on long documents. Ask for one page of results at a time, or narrower filters. * **Expired or invalid credential.** When the API returns 401, the tool replies “Your fileAI connection has expired or is no longer valid. Reconnect fileAI in your Claude connector settings, then try again.” You get this wording in every client. With an API key (Codex, Cursor, ChatGPT, VS Code), check the key in your client’s config instead, and that it was issued by the same instance as your server URL. * **Project not in this connection.** When you signed in and a tool is called with a `project_id` your connection can’t reach, the result has `projectNotInConnection: true`, the `projectId` and the `projects` you can reach. Either the project’s workspace wasn’t selected when you signed in, or your account can’t open the project. To add it, disconnect and reconnect fileAI, and select that workspace when you sign in. See [Choosing a project](/mcp/overview#choosing-a-project). * **Read-only keys.** A read-only API key can only call tools that read. Anything that uploads, edits, deletes or starts a forensics run is refused. ## [​ ](#related) Related ## fileAI MCP server Server URLs, sign-in and safety guards. ## Connect a client Set up Claude, Codex, Cursor, ChatGPT or VS Code. ## Claude details Projects, file uploads and troubleshooting in Claude. [Previous](/mcp/connect)[ Claude details What to know after you connect Claude: projects, file uploads, disconnecting and fixing problems. Next ](/mcp/claude) ⌘I ## On this page Back to top * [Parameters every tool shares](#parameters-every-tool-shares) * [Account and projects](#account-and-projects) * [Files and uploads](#files-and-uploads) * [Uploading a file](#uploading-a-file) * [Values and schemas](#values-and-schemas) * [File types](#file-types) * [Folders](#folders) * [Forensics](#forensics) * [Workflows](#workflows) * [Workspace](#workspace) * [Guided prompts](#guided-prompts) * [Limits and errors](#limits-and-errors) * [Related](#related)