Frenchie Kit documentation

Quick start

Three things. Account, install, then login when you want Kit file tools.

1. Create an account

Sign up at getfrenchie.dev/register. You get 100 free credits on your first signup, once per email — no credit card required.

You do not need to copy an API key for the normal local setup. The CLI login command creates one after you approve it in the browser.

2. Install Frenchie in your agent

From the root of your project:

npx @lab94/frenchie install

The installer auto-detects your agent, copies the skill files, and writes a project-scoped stdio MCP config. Method text workflows work immediately. Kit file tools connect after login.

3. Connect Frenchie Kit tools

When you want OCR, transcription, extraction, or image generation, run:

npx @lab94/frenchie login

The CLI shows a browser approval URL, waits for approval, then writes the API key into the same MCP config. Restart your agent after login.

You can also target a specific agent explicitly:

# Project-scoped (default):
npx @lab94/frenchie install --agent claude
npx @lab94/frenchie install --agent cursor
npx @lab94/frenchie install --agent codex
npx @lab94/frenchie install --agent vscode
npx @lab94/frenchie install --agent gemini

# User-level (requires --global):
npx @lab94/frenchie install --agent antigravity   --global
npx @lab94/frenchie install --agent windsurf       --global
npx @lab94/frenchie install --agent zed            --global
npx @lab94/frenchie install --agent claude-desktop --global

User-level installs (Antigravity, Claude Desktop) need the --global flag — auto-detect never writes under $HOME.

Upgrading later

When a new Frenchie version ships, the pinned package spec inside each MCP config needs to point at the new version so npx stops serving a cached older bundle. Two upgrade commands cover everything — the flag picks scope, cwd doesn't matter:

# Project-scoped configs in this directory
npx @lab94/frenchie@latest install

# Every $HOME config that already has frenchie (Antigravity, Claude Desktop, etc.) — cwd irrelevant
npx @lab94/frenchie@latest install --global

install --global is upgrade-mode: it only rewrites frenchie entries that already exist in $HOME configs. It will not surprise-install anything new. First-time global installs still go through install --agent <name> --global.

Then ask your agent in plain English, or use the shortcuts where supported:

"OCR ./report.pdf with Frenchie"
"Transcribe ./meeting.mp3 and pull out action items"
"Extract ./forecast.xlsx to Markdown"
/ocr invoice.pdf
/transcribe meeting.mp3
/extract forecast.xlsx

For hosted / web agents (HTTP)

Lovable, Manus, Claude.ai, ChatGPT.com, Mistral Le Chat — these can't spawn local binaries. Connect them to the public HTTP endpoint instead:

Claude Code (CLI flag, for reference):

claude mcp add --transport http frenchie https://mcp.getfrenchie.dev --header "Authorization: Bearer fr_your_key_here"

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "frenchie": {
      "url": "https://mcp.getfrenchie.dev",
      "headers": {
        "Authorization": "Bearer fr_your_key_here"
      }
    }
  }
}

Codex — add to ~/.codex/config.toml:

[mcp_servers.frenchie]
url = "https://mcp.getfrenchie.dev"

[mcp_servers.frenchie.headers]
Authorization = "Bearer fr_your_key_here"

In HTTP mode, agents upload the file first via upload_file, then call OCR/transcription with uploaded_file_reference. The skill pack handles this automatically — install it the same way:

npx @lab94/frenchie install --agent claude
npx @lab94/frenchie install --agent cursor
npx @lab94/frenchie install --agent codex

Pick your agent

Every agent handles MCP a little differently. Pick yours for the exact invocation syntax and the gotchas we've hit in dogfood.

Something not working? See the symptom-first troubleshooting guide.

MCP tools

Frenchie exposes five core tools through MCP: ocr_to_markdown, transcribe_to_markdown, extract_to_markdown, generate_image, and get_job_result. Your agent picks the right one automatically.

ocr_to_markdown

Converts a PDF or image to Markdown using OCR.

Parameters:

* One of file_path or uploaded_file_reference is required.

Supported file types:

application/pdf    image/png    image/jpeg    image/webp

Credits: 1 per page.

Routing:

Response (done — stdio mode):

{
  "status": "done",
  "savedTo": ".frenchie/invoice/result.md",
  "wordCount": 312,
  "imageCount": 1,
  "creditsUsed": 4,
  "resultExpiresAt": "2026-04-10T15:30:00Z"
}

Stdio mode returns metadata only. The full markdown is written to savedTo on disk — read that file with your agent's file tool if you need the content. This keeps tool responses from flooding the agent's context window (a 17-page PDF drops from ~25k tokens to ~200 bytes).

Response (done — HTTP mode):

{
  "status": "done",
  "markdown": "# Invoice\n\n| Item | Amount |\n|------|--------|\n| Widget | $42.00 |",
  "creditsUsed": 4,
  "resultExpiresAt": "2026-04-10T15:30:00Z"
}

HTTP mode keeps the markdown inline because remote clients have no local disk — there's no savedTo path they could read back. Images in the markdown are uploaded to server-side storage and referenced as frenchie-result: keys; fetch them with fetch_result_file.

Response (processing, both modes):

{
  "status": "processing",
  "jobId": "fr_job_29xk",
  "estimatedCompletion": "2026-04-10T15:02:30Z"
}

transcribe_to_markdown

Converts audio or video to a Markdown transcript.

Parameters:

* One of file_path or uploaded_file_reference is required.

Supported file types:

Audio:  audio/mpeg  audio/mp3  audio/m4a  audio/wav  audio/x-wav  audio/wave  audio/mp4  audio/webm
Video:  video/mp4  video/quicktime (MOV)  video/webm

Credits: 2 per minute (rounded up).

Routing: Determined by duration + file size. Short clips may resolve sync. Longer files go async — chunked and reassembled automatically.

Response format: Same as ocr_to_markdown.

extract_to_markdown

Converts DOCX, XLSX, CSV, TSV, or PPTX files to Markdown. This is file extraction, not document intelligence: Frenchie reads the file and returns Markdown; your agent handles summaries, fields, and decisions after that.

Parameters:

* One of file_path or uploaded_file_reference is required.

Supported file types:

DOCX    XLSX    CSV    TSV    PPTX

Credits: DOCX 0.5 credit/page, XLSX 0.5 credit/sheet, CSV/TSV 0.5 credit/file, PPTX 1 credit/slide.

Size caps: DOCX, XLSX, and PPTX up to 50 MB. CSV and TSV up to 20 MB.

Response format: Same Markdown result contract as ocr_to_markdown. Stdio mode auto-saves to .frenchie/<name>/result.md; HTTP mode uploads first and the agent persists the final Markdown locally.

generate_image

Generates a single image from a text prompt through Frenchie image generation.

Parameters:

Credits: 20 per image, refunded automatically on failure.

Limits: 50 images per hour, 250 images per day per user. v1 generates one image per call — call again for additional variants.

Response (done — stdio mode):

{
  "status": "done",
  "jobId": "fr_job_img_29xk",
  "creditsUsed": 20,
  "resultExpiresAt": "2026-04-23T15:30:00Z",
  "result": {
    "kind": "image",
    "format": "png",
    "mimeType": "image/png",
    "size": "1024x1024",
    "savedTo": ".frenchie/ramen-poster/generated.png"
  }
}

Stdio mode auto-downloads the image and writes it to result.savedTo next to your work. Tell the user the relative path; the file is already on disk.

Response metadata:

Response (done — HTTP mode):

{
  "status": "done",
  "jobId": "fr_job_img_29xk",
  "creditsUsed": 20,
  "resultExpiresAt": "2026-04-23T15:30:00Z",
  "result": {
    "kind": "image",
    "format": "png",
    "mimeType": "image/png",
    "size": "1024x1024",
    "imageUrl": "https://minio.getfrenchie.dev/...?signed=true"
  }
}

HTTP mode returns a presigned URL that expires in 30 minutes. Download the image to the user's machine (or render it inline) before the URL expires; the underlying object is deleted shortly after.

Missing prompts, insufficient credits, and provider failures use the standard MCP error envelope in the Errors section below.

get_job_result

Retrieves the result of an async job.

Most of the time you don't need to call this directly — the MCP server auto-polls for up to 90 seconds after submitting a job. You only need get_job_result if the auto-poll timed out and returned a "processing" status.

Parameters:

Response shape is the same as whichever tool submitted the job (see ocr_to_markdown above) — stdio returns metadata with savedTo, HTTP inlines markdown.

Response (done — stdio mode):

{
  "status": "done",
  "savedTo": ".frenchie/meeting/result.md",
  "wordCount": 4821,
  "imageCount": 0,
  "creditsUsed": 96,
  "resultExpiresAt": "2026-04-10T15:30:00Z"
}

Response (done — HTTP mode):

{
  "status": "done",
  "markdown": "...",
  "creditsUsed": 96,
  "resultExpiresAt": "2026-04-10T15:30:00Z"
}

Response (still processing):

{
  "status": "processing",
  "jobId": "fr_job_29xk",
  "estimatedCompletion": "2026-04-10T15:02:30Z"
}

Sync and async routing

You don't pick sync or async — Frenchie does.

Small files (single-page PDFs, short clips) resolve sync — the result comes back in the same request.

Larger files go async:

1. Frenchie returns a jobId immediately
2. The MCP server auto-polls every 3 seconds for up to 90 seconds
3. If the job finishes within that window, you get the result back transparently
4. If it doesn't, you get { "status": "processing", "jobId": "..." } — call get_job_result later

For most files, the auto-poll handles everything. Your agent doesn't need to know or care about the difference.

Supported files

OCR (→ Markdown):

Transcription (→ Markdown):

Image generation (text prompt → image):

Image generation takes a text prompt instead of a file upload. Sizes: 1024x1024, 1536x1024, 1024x1536, or auto.

Limits:

If you send an unsupported type, you'll get a 400 with "Unsupported file type for [filename]".

Credits

Everything runs on credits. No subscriptions, no monthly fees.

$1 = 100 credits. That gets you 100 OCR pages, 50 minutes of transcription, or 5 generated images. New accounts start with 100 free credits. Failed jobs are refunded automatically.

Credit packs:

First-time email signups get 100 free credits, once per email. No card required. Credits don't expire.

If your balance is too low for a job, the request fails with a 402:

{
  "isError": true,
  "content": [{ "type": "text", "text": "Insufficient credits" }]
}

The response also includes your current balance and the required amount, so your agent (or you) knows exactly how many credits to top up.

Rate limits

Generous enough that you probably won't hit them. But here they are.

If you exceed a limit, you'll get a 422 with details on what you hit and when it resets.

For most users, these limits are invisible. If you're consistently hitting them, reach out — we want to hear about your use case.

Result expiry

Results are available for 30 minutes after first delivery. After that, Markdown content or generated-image URLs are deleted and the API returns 410 Gone.

{
  "isError": true,
  "content": [{ "type": "text", "text": "Job result has expired and is no longer available" }]
}

The job record stays in the system (for your usage history), but the actual content is gone. If you need the result again, re-submit the file or prompt.

We don't store your files or results longer than necessary. That's the point.

Errors

When something goes wrong, Frenchie returns a standard MCP error:

{
  "isError": true,
  "content": [{ "type": "text", "text": "<error message>" }]
}

Here's what you might see:

Most errors are self-explanatory. If you hit a 500, it's on us — retry once, and if it persists, let us know at support@getfrenchie.dev.

API key

The recommended local path is npx @lab94/frenchie login, which creates a CLI API key after browser approval and writes it to your MCP config. You can also create or revoke keys from your dashboard.

Format: fr_ followed by 32 hex characters.

fr_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Two ways to authenticate:

1. CLI login (recommended): Run npx @lab94/frenchie login. The CLI writes FRENCHIE_API_KEY into the detected MCP config.
2. Manual key: Set FRENCHIE_API_KEY in your MCP config, rerun npx @lab94/frenchie install --api-key fr_..., or pass api_key in a tool call when you manage multiple accounts.

Permanent API key records are hashed (SHA-256). CLI login holds the newly created key only long enough to deliver it to your terminal, then clears the plaintext.

If your key is compromised, revoke it from the dashboard and generate a new one. Active jobs will finish, but new requests with the old key will be rejected.

Upgrading from an older Frenchie

Frenchie 0.3.0 ships three changes that affect existing installs: stdio tool responses are now metadata-only (markdown stays on disk), MCP configs use absolute npx paths so GUI agents work, and mcp --help / --version / --selftest now short-circuit instead of hanging.

If you're on 0.2.x

Re-run install. That's it.

cd <your project>
npx @lab94/frenchie@latest install --api-key fr_your_key_here

Restart your agent fully (not a soft reload) — MCP subprocesses persist across reloads on some agents.

If you're on 0.1.x (HTTP-primary)

0.2.0 switched the primary integration path from HTTP to stdio. The old HTTP entry at user or local scope will shadow the new project stdio entry — you have to remove it first:

Claude Code:

claude mcp list                      # check scope
claude mcp remove frenchie -s local  # or -s user / -s project as needed

Cursor:

Edit ~/.cursor/mcp.json and remove the frenchie block that has a url field.

Codex:

Edit ~/.codex/config.toml and remove any [mcp_servers.frenchie] block with url = "...".

Then re-run install and restart your agent. Verify with claude mcp list (or equivalent) that the entry now shows a command: "/.../npx" rather than a URL.

For the full upgrade guide with every version gap (including 0.3.0 → 0.3.1 critical pin fix and 0.3.1 → 0.3.2 API key reuse), see the migration guide.

FAQ