Documentation

Quick start

Three things. Account, skills, and a file to parse.

1. Create an account

Sign up at getfrenchie.dev/register. You get 100 free credits — no credit card required.

Once you're in, grab your API key from the dashboard. It looks like this:

fr_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Keep it somewhere safe. You'll need it in the next step.

2. Install the MCP server & skills

Add Frenchie to your MCP config. The package is @lab94/frenchie.

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "frenchie": {
      "command": "npx",
      "args": ["-y", "@lab94/frenchie"],
      "env": {
        "FRENCHIE_API_KEY": "fr_your_key_here"
      }
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "frenchie": {
      "command": "npx",
      "args": ["-y", "@lab94/frenchie"],
      "env": {
        "FRENCHIE_API_KEY": "fr_your_key_here"
      }
    }
  }
}

VS Code — add to .vscode/mcp.json:

{
  "mcpServers": {
    "frenchie": {
      "command": "npx",
      "args": ["-y", "@lab94/frenchie"],
      "env": {
        "FRENCHIE_API_KEY": "fr_your_key_here"
      }
    }
  }
}

Default transport is stdio. For HTTP mode in production, the endpoint is https://api.getfrenchie.dev/mcp.

Install slash commands:

$ npx @lab94/frenchie install

This auto-detects your agent and installs /ocr, /transcribe, and /frenchie-status commands. Skills ensure your agent uses Frenchie correctly even if it doesn't call MCP tools directly.

Supported agents: Claude Code, Cursor, Codex CLI, Antigravity. You can also target a specific agent:

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

3. Parse something

Tell your agent to use Frenchie — or just use the slash commands:

"Parse this PDF and summarize the key findings"
"Transcribe this recording and pull out the action items"

// Or use slash commands directly:
/ocr invoice.pdf
/transcribe meeting.mp3

Your agent calls the right Frenchie tool, gets clean Markdown back, and keeps working. That's it.

MCP tools

Frenchie exposes three tools through MCP. 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):

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

Response (processing):

{
  "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.

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 (done):

{
  "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.

                 small file
agent ──────────► Frenchie ──────────► result (sync, ~2s)

                 large file
agent ──────────► Frenchie ──► jobId ──► auto-poll (up to 90s) ──► result
                                            │
                                            └── if timeout: agent calls get_job_result later

Supported files

OCR (→ Markdown):

Transcription (→ Markdown):

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.

Credit packs:

New accounts get 100 free credits. 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, the Markdown content is 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.

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

Your API key is created when you sign up. Find it on your dashboard.

Format: fr_ followed by 32 hex characters.

fr_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Two ways to authenticate:

1. Environment variable (recommended): Set FRENCHIE_API_KEY in your MCP config. The server reads it on startup.
2. Per-request parameter: Pass api_key in any tool call. This overrides the env key for that specific request — useful if you're managing multiple accounts.

Your key is hashed (SHA-256) before storage. We never store it in 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.

FAQ