> ## Documentation Index
> Fetch the complete documentation index at: https://filecheck.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect ChatGPT, Claude, Cursor, Codex or any MCP client to Filecheck, then ask it to check and fix print files and set up your products.

> [!TIP]
>
> Using an AI agent such as Claude Code, Codex or Cursor? Give it the [Quickstart for agents](https://filecheck.io/docs/mcp/quickstart-agents.md) and it connects itself.

`filecheck-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server for the Filecheck API. It lets AI tools work in your Filecheck account. The hosted server is at:

```
https://api.filecheck.io/mcp
```

## What you can do

* **Check files:** preflight a PDF or image, fix bleed, colour and fonts, validate PDF/A and PDF/UA, make files smaller, and render page previews. Every file it checks is a normal Filecheck job on your account, so it shows up in your dashboard like any other.
* **Set up your products:** build workflows, upload rules and preflight profiles for a product, try them on a real file, and make your Shopify products open them. See [Set up products with AI](https://filecheck.io/docs/mcp/set-up-products.md).
* **Delivery and webhooks:** send finished files to SFTP and FTP hotfolders, S3, email or a webhook, with a test delivery first, and set up webhooks for job and proof events. See [Set up delivery with AI](https://filecheck.io/docs/mcp/delivery.md).
* **Storefront:** change how the Filecheck upload box appears on your product pages.
* **Jobs:** find past jobs, read their full preflight reports, and download the fixed files.

New workflows, rules and profiles are saved as drafts, so the agent can try them on a real file before anything goes live. Agents are told to ask you before they publish a draft, map a product or change your storefront settings, because those show on your store at once. Every tool that changes your account is also marked as such, so ChatGPT, Claude and other clients ask you before it runs.

## Before you start

Open the [Dev Hub](https://admin.filecheck.io/devhub) in your Filecheck dashboard, under **API keys**, and copy a secret key (`sk_…`). Create one per AI tool and label it, so you can revoke one without the others. The key goes in your AI tool's settings or on the Filecheck sign-in page; the model never sees it.

> [!WARNING]
>
> The secret key grants full API access to your account. Keep it in your MCP client's local settings or a server-side environment variable, never in a repository or a browser. You can revoke it in the Dev Hub at any time.

Chat apps connect to the hosted server and sign in: you paste a secret key once, on a Filecheck page, and the app gets its own access from then on. Coding tools can run the server locally with `npx`, which needs [Node.js](https://nodejs.org) 18 or later; the local server reads files straight from your disk and saves the fixed copy next to them. Either way, file bytes go to Filecheck over a presigned upload, never through the model's context.

## ChatGPT

1. **Add the server:** turn on developer mode and add a custom MCP server ([OpenAI's guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt) shows where, for your plan). Name it Filecheck, use the URL `https://api.filecheck.io/mcp` and choose **OAuth** authentication.
2. **Connect:** ChatGPT opens a Filecheck page. Paste your secret key and click **Allow access**.
3. **Test:** ask *"Which workflows does my Filecheck account have?"*

ChatGPT can't hand a file attached to the chat to Filecheck. Give it a link to the file instead: any public URL that downloads it, such as a shared Dropbox or Google Drive link.

> [!NOTE]
>
> ChatGPT keeps the list of tools it saw when you added the server. When Filecheck adds new tools, open the connection in ChatGPT's settings, click **Refresh**, and start a new chat. On a Business or Enterprise workspace, an admin may need to refresh it.

## Claude

1. **Add the connector:** on claude.ai, open **Settings → Connectors** and click **Add custom connector**. Name it Filecheck and use the URL `https://api.filecheck.io/mcp`.
2. **Connect:** click **Connect**. Claude opens a Filecheck page: paste your secret key and click **Allow access**.
3. **Test:** ask *"Which workflows does my Filecheck account have?"*

The connector then works in Claude on the web, desktop and mobile. If your organization only allows connectors an admin has approved, ask them to add it.

## Claude Desktop

To let Claude Desktop read and save files on your computer, run the local server instead of the connector. Open **Settings → Developer → Edit Config** and add Filecheck to `claude_desktop_config.json`, then restart Claude Desktop:

```json claude_desktop_config.json theme={null}
{
  "mcpServers": {
    "filecheck": {
      "command": "npx",
      "args": ["-y", "filecheck-mcp"],
      "env": { "FILECHECK_API_KEY": "sk_…" }
    }
  }
}
```

## Claude Code

Run in your terminal:

```bash theme={null}
claude mcp add filecheck \
  -e FILECHECK_API_KEY=sk_… \
  -- npx -y filecheck-mcp
```

Or connect to the hosted server and sign in: run `claude mcp add --transport http filecheck https://api.filecheck.io/mcp`, then `/mcp` in Claude Code, pick filecheck and choose **Authenticate**. Your browser opens the Filecheck page.

## Cursor

Add to `~/.cursor/mcp.json`:

```json ~/.cursor/mcp.json theme={null}
{
  "mcpServers": {
    "filecheck": {
      "command": "npx",
      "args": ["-y", "filecheck-mcp"],
      "env": { "FILECHECK_API_KEY": "sk_…" }
    }
  }
}
```

## VS Code

Add to `.vscode/mcp.json`. VS Code asks for the key when the server starts, so it is never written to the file:

```json .vscode/mcp.json theme={null}
{
  "inputs": [{
    "type": "promptString",
    "id": "filecheck-key",
    "description": "Filecheck secret key",
    "password": true
  }],
  "servers": {
    "filecheck": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "filecheck-mcp"],
      "env": {
        "FILECHECK_API_KEY": "${input:filecheck-key}"
      }
    }
  }
}
```

## Codex

Add to `~/.codex/config.toml`:

```toml ~/.codex/config.toml theme={null}
[mcp_servers.filecheck]
command = "npx"
args = ["-y", "filecheck-mcp"]
env = { FILECHECK_API_KEY = "sk_…" }
```

## Any MCP client (hosted server)

If your client cannot run `npx`, or you are building your own agent, connect to the hosted server over Streamable HTTP. Clients that support MCP sign-in (OAuth) find the Filecheck sign-in page on their own, as ChatGPT and Claude do. Anything else sends the key as a Bearer header:

| | |
| - | - |
| URL | `https://api.filecheck.io/mcp` |
| Header | `Authorization: Bearer sk_…` |

For example, in Claude Code:

```bash theme={null}
claude mcp add --transport http filecheck https://api.filecheck.io/mcp \
  --header "Authorization: Bearer sk_…"
```

The hosted server has the same tools, minus local files: sources are links or files uploaded earlier, and `save_artifact` is not available. Long jobs return `pending: true` after about 20 seconds; the agent then polls with `get_job`.

> [!NOTE]
>
> A signed-in app acts with the same access as the secret key you pasted. Revoking that key in the Dev Hub disconnects the app at its next request.

## Example requests

* "Check business-card.pdf for print. Fix what you can and save the print-ready copy next to it."
* "Validate every PDF in ./invoices for PDF/A and list the ones that fail, with the reason."
* "Which jobs failed this week, and what was wrong with them?"
* "Set up business cards at 85 × 55 mm with 3 mm bleed as a draft workflow, and try it on business-card.pdf."
* "Make the Premium Business Cards product in my Shopify store open that workflow."
* "Send finished files to our SFTP hotfolder and test the delivery."

## Tools

### Check files

| Tool | What it does |
| - | - |
| `check_file` | Preflight a file against a profile, rule or workflow (drafts included, to try one before it goes live); returns the verdict, the findings and a recommended fix |
| `fix_file` | Preflight, apply safe automatic fixes, check again; returns the fixed file |
| `validate_pdf` | PDF/A and PDF/UA conformance via veraPDF |
| `optimize_file` | Downsample, recompress and slim a PDF or image |
| `render_previews` | Render page preview images, so the agent can look at a file |
| `get_report` | Drill into the full preflight report, section by section |
| `list_jobs` | Recent jobs as lean envelopes, filterable by order |
| `get_job` | Poll a job and get fresh download URLs |
| `delete_job` | Soft-delete a job and its files |
| `save_artifact` | Save a fixed file to a local path (local server only) |

### Set up your account

| Tool | What it does |
| - | - |
| `list_catalog` | Browse your workflows, rules, preflight profiles, connectors and optimize presets, with your drafts if asked |
| `setup_reference` | Read the schema of a setup record (every field and its allowed values) before changing it |
| `manage_catalog` | Create, update, delete, publish or revert a workflow, rule, profile, connector or optimize preset; new records are drafts until published |
| `list_destinations` | Where finished files are delivered: SFTP and FTP hotfolders, S3, webhooks, email |
| `manage_destination` | Create, update or delete a delivery destination; passwords and keys are write-only |
| `test_destination` | Deliver a sample order through a destination and report whether it arrived |
| `list_product_maps` | Which products in your Shopify store open which workflow |
| `find_store_products` | Read products from your connected Shopify store |
| `map_product` | Make a Shopify product open a published workflow, or stop it |
| `get_settings` | How the Filecheck Element appears on your product pages |
| `update_settings` | Change those storefront settings |
| `list_webhooks` | Your webhook endpoints and the events they can subscribe to |
| `manage_webhook` | Create, update or delete a webhook endpoint |
| `test_webhook` | Send a signed test event and report the receiver's answer |

Every create and update can run as a dry run first: the record is checked and shown as it would be saved, and nothing changes. When the API refuses a record, the agent gets the field at fault and every problem, and fixes them before trying again. Drafts that are never published are deleted after 30 days.

On WooCommerce, PrestaShop and OpenCart, a product's workflow is chosen in the Filecheck plugin's product settings, so the agent builds the workflow and you pick it there.

## Reading results

Every job carries two independent fields, and agents are instructed to read both:

* **`status`**: did the check *run*: `pending`, `running`, `done`, `skipped` or `error`.
* **`outcome`**: the *verdict*: `pass`, `warn`, `fail`, `fixed`, `unchanged`, `na` or `mixed`.

`status: done` with `outcome: fail` means the check completed and the file is **not** print-ready. The same [two-axis model](https://filecheck.io/docs/server/verify-jobs.md) applies across the whole API.

> [!NOTE]
>
> Download URLs are presigned and expire after about 60 minutes. `get_job` returns freshly signed URLs on every call, so agents fetch them again instead of storing links.

## Pricing

The server is free and open source (MIT). Files an agent checks are normal Filecheck jobs on your account, billed like any other job. See [pricing](https://filecheck.io/pricing).

The package is on [npm](https://www.npmjs.com/package/filecheck-mcp) and developed at [github.com/PrintApp/filecheck-integrations](https://github.com/PrintApp/filecheck-integrations).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.