RAG Converter MCP for agents
The ragconverter-mcp server lets an agent convert documents through the same API as a script - health, balance, and convert tools - using an API key the account owner configured once; MCP cannot sign in or pay through Stripe, it only spends prepaid credit.
Do you need MCP?
No. Any agent that can send HTTP requests can call POST /v1/convert with a Bearer API key - curl, Python, a CI job, or a custom tool in your framework. MCP is optional: a thin wrapper so Cursor and Claude Desktop discover tools by name instead of you wiring the multipart upload yourself. If your agent already speaks HTTP, skip MCP and use the API page at ragconverter.com/api or the developer guide linked below.
What a human sets up once
An agent cannot open Stripe or create an account on its own. Before MCP works, someone signs in at ragconverter.com, tops up prepaid credit on Account → Billing, and mints an API key under Account. That key goes in the MCP server environment as RAGCONVERTER_API_KEY - never in a chat message and never as a tool argument. Optional: turn on automatic top-up so a long pipeline does not stop at zero credit. The browser converter stays free and local; MCP always uses the paid API on Fly.
Install the MCP server
Install from npm: npm install -g ragconverter-mcp. In Cursor or Claude Desktop set command to ragconverter-mcp and pass RAGCONVERTER_API_KEY in env. Optional RAGCONVERTER_API_BASE defaults to https://api.ragconverter.com. Example Cursor config: command ragconverter-mcp, env with your key, restart the editor after saving MCP settings. The package also lives in this repo under tools/ragconverter-mcp if you prefer to build from source.
Tools the agent gets
ragconverter_health asks GET /health with no key - useful before a batch to see whether OCR, speech or semantic embeddings are up on this instance. ragconverter_balance and ragconverter_usage need the key and report prepaid credit and monthly file counts. ragconverter_convert takes local file paths, optional engines for video (ocr, vlm, asr), and an output directory; it POSTs multipart to /v1/convert and writes chunks.jsonl plus manifest.json to disk, then returns a short JSON summary (paths, line count, manifest). The full embedding payload stays in the file - not inlined into the chat.
Billing and failure modes
Each convert draws down the same prepaid balance as any other API call. When credit is gone the API answers 402 and the tool returns an error telling the human to top up - the agent cannot fix that itself unless auto-recharge is already enabled on a saved card. Revoke a leaked key under Account without touching the rest of the stack. For production pipelines, check balance before large folders and handle 402 by notifying a person rather than retrying forever.