LLM Agent Integration (MCP)

adf-mcp is a server that exposes the AI Data Foundry document analysis workflow as MCP (Model Context Protocol) tools. Once registered in an LLM client such as Claude Code, Claude Desktop, Cursor, or Codex CLI, you can upload local document files to a project and receive analysis results directly in the conversation.

An LLM agent performs the installation and registration for you, so there is no need to type commands yourself. Authentication uses an API key.

This document covers calling AI Data Foundry from an LLM client. For the opposite direction — pulling files from an external MCP server into a project — see MCP Ingestion.

Prerequisites

An API key must be issued. Create one under User Menu > API Keys; see Authentication for the full procedure.
The API key user must have admin permission on the target project.
The target project must have an active workflow configured. Without one, execution returns an error, so create it first by following Creating a Workflow.
Installation is performed from a coding agent that can run shell commands (Claude Code, Cursor Agent, Codex CLI, etc.). To register the server in a client without shell access (e.g., Claude Desktop without tools connected), install it from a coding agent first and then register it in that client.

Supported platforms are macOS (Apple Silicon and Intel), Linux (x86_64 and arm64), and Windows (x64 and ARM64). It is a single executable with no runtime dependencies.

Installation

Enter the following sentence in your coding agent as is.

Read http://sveltekit-prerender/static/mcp/install.md and proceed with the installation

The agent reads the installation instructions and performs the following steps in order.

Detects the OS and architecture, downloads the matching executable, and verifies its checksum.
Installs the executable. (~/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\adf-mcp on Windows)
Asks for your API key. Provide the key issued under User Menu > API Keys.
Confirms which MCP client to register with, then adds the server to that client's configuration.
Calls the list_projects tool to verify that your projects are listed, and reports a summary of the result.

The agent is instructed never to guess or fabricate the API key and to always ask you for it.
Issuing the key before you start lets the installation proceed without interruption.

Registration Example

The configuration generated by the agent looks like the following. Use it as a reference when registering manually or moving the server to another MCP client. <BIN> is the absolute path of the installed executable.

{
  "mcpServers": {
    "adf": {
      "command": "<BIN>",
      "env": {
        "ADF_API_KEY": "<your API key>"
      }
    }
  }
}

Environment Variable	Required	Description
`ADF_API_KEY`	Yes	Your issued API key
`ADF_DEFAULT_PROJECT_ID`	No	The project ID (`publicId`) to use by default when the key can access multiple projects

The configuration location for each client is as follows.

Client	Configuration Location
Claude Code	`claude mcp add adf --scope user -e ADF_API_KEY=<key> -- <BIN>` command, or `.mcp.json`
Claude Desktop	macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`~/.cursor/mcp.json`
Codex CLI	`~/.codex/config.toml`

Usage

Once registered, the following tools are available.

Tool	Description
`list_projects`	Lists the projects (ID and name) owned by the API key user.
`parse_file`	Uploads a local file to a project, waits for the workflow to finish, and downloads the result files. Returns the path where the results were saved.
`check_result`	Checks whether a document whose result was not yet received has finished processing, and downloads the result once available.

Request Example

Analyze ~/Documents/contract.pdf with AI Data Foundry and show me the result

When the agent calls parse_file, the upload, workflow execution, completion wait, and result download happen in one step. The contents of the result ZIP depend on the last component of the workflow; see Project Workflow Integration for details.

Running a workflow consumes credits, exactly as when running it from the web interface.
If processing does not finish within the default wait time (3 minutes), the document UUID is returned. You can fetch the result afterwards with check_result.
If the workflow includes a review step, the result is not available until the review is completed. Finish the review in the web interface, then call check_result.
Result files are stored in a temporary folder on your PC and deleted automatically after 24 hours, so move them elsewhere if you want to keep them.

Updating

On startup, the server checks whether a new version is available and, if so, includes a notice in the tool response. When the agent relays this notice, enter the same sentence you used for installation.

Read http://sveltekit-prerender/static/mcp/install.md and proceed with the installation

The existing installation is detected and only the executable is replaced; the client registration and API key settings are kept as they are. Restart the MCP client after the replacement to apply the new version.

Security

The MCP configuration file stores the API key in plain text. Because the key allows actions that require project admin permission, treat it like a password.

Security Guidelines

Never commit configuration files (such as .mcp.json) to a code repository
On macOS/Linux, restrict the configuration file so only you can read it (chmod 600 <config file>)
Delete keys you no longer use under User Menu > API Keys

Troubleshooting

Symptom	Action
Download or checksum verification fails during installation	Check your network and proxy environment, then retry. If it keeps failing, contact us.
"Unidentified developer" warning on macOS	Remove the quarantine attribute with `xattr -d com.apple.quarantine <BIN>`.
The client cannot find the server	Make sure `command` in the configuration is the absolute path of the executable. The `~` notation is not expanded.
`list_projects` returns an error	Verify that the API key is valid and that it belongs to an admin of the target project.
"No active flow" error on execution	Occurs when the project has no active workflow. Create a workflow and set it as the active flow by following Creating a Workflow, then try again.