File Convert Online Logo
Upgrade
Back to Blog
general

FileConvert MCP Server: README

Reference for the file-convert.online MCP server: the eight tools, authentication with API keys, supported formats, credits, rate limits, retention, security and client setup.

Rumen AtanasovSeptember 14, 2026Updated October 7, 20267 min read
AI AgentsAPIMCP

This is the reference page for the file-convert.online MCP (Model Context Protocol) server. It gives AI agents and coding assistants such as Claude, Cursor, VS Code Copilot, Windsurf and n8n the ability to convert files between more than 110 formats through a single remote, hosted endpoint. If you want the two-minute version, read the quickstart at file-convert.online/blog/file-convert-mcp-server-quickstart. Common questions are answered in the FAQ at file-convert.online/blog/file-convert-mcp-server-faq.

Endpoint and transport

  • Endpoint: https://file-convert.online/api/mcp/v1/mcp
  • Transport: MCP Streamable HTTP (protocol revision 2025-06-18 and later). The server is stateless: every request is self-contained, so there are no sessions to keep alive and any number of clients can share one key.
  • Authentication: an API key sent as an Authorization: Bearer fc_live_... header. OAuth is not required and not offered yet.
  • REST twin: every tool wraps a documented public REST endpoint. The OpenAPI 3 description lives at https://file-convert.online/api/mcp/openapi.json (YAML at /api/mcp/openapi.yaml).

Tools

Eight tools cover the whole conversion workflow. Formats are named by extension, the way people say them: png, webp, docx, pdf, mp3, mp4, epub, zip.

  • convert_file(source_url, source_format, target_format): one call for any file reachable by URL. The server fetches it (with SSRF protection), uploads it and starts the job. Returns job_id and file_id.
  • upload_file(filename, content_base64): upload bytes the agent holds locally, up to 25 MiB. Returns file_id. Use it when the file is not reachable by URL, for example a document the user pasted into a chat client.
  • start_conversion(file_id, source_format, target_format): start a job for an already uploaded file, including the output of a previous job. Returns job_id.
  • get_job_status(job_id): Pending, Processing, Completed or Failed (with the reason). Most jobs finish within seconds; poll every two or three seconds.
  • get_download_url(job_id or file_id): the URL of the result. It needs no authentication (the unguessable file id is the capability), so the agent can hand it straight to the user. Results stay downloadable for about an hour by default.
  • get_balance(): remaining credits of the account behind the key, plus the pricing page.
  • list_formats(format_type?): the full catalogue, optionally filtered to one category. Only needed when you are unsure what is supported.
  • get_upload_url(filename): raw multipart upload instructions for agents that can run HTTP themselves.

Both formats of a conversion must belong to the same category: image to image, document to document, and so on. Should an extension ever appear in more than one category, the optional format_type hint selects it; today every extension maps to exactly one category, so the hint is rarely needed. Numeric ids from list_formats are still accepted through source_format_id and target_format_id for older clients.

Supported formats

Six categories, more than 110 formats in total. A few representative members of each:

  • Image: png, jpg, webp, gif, heic, svg, tiff, bmp, psd, ico and more.
  • Document: pdf, docx, doc, odt, rtf, txt, xlsx, xls, csv, pptx, ppt.
  • Audio: mp3, wav, m4a, flac, aac, ogg, opus, wma and more.
  • Video: mp4, mov, mkv, avi, webm, wmv, flv, m4v and more.
  • Archive: zip, 7z, tar, gz, bz2, xz, rar, iso, dmg and more.
  • Ebook: epub, mobi, azw3, fb2, djvu, htmlz.

Call list_formats for the authoritative, current list; it is the same catalogue the website uses.

Credits, plans and rate limits

Every conversion costs credits, reserved when the job starts and refunded if it fails. Image conversions cost 1 credit; document, audio, archive and ebook conversions cost 2; video conversions cost 5. Free accounts receive a daily package of 10 credits whenever their balance is at zero, which is enough to try things out. Paid plans on file-convert.online/pricing add monthly credit allowances and higher rate limits.

Requests are rate limited per 60-second window. Free accounts get 120 requests per minute on public endpoints and 60 on authenticated ones; Plus and Pro plans raise those limits several times over. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, and a 429 answer includes Retry-After. The MCP server turns a 429 into a tool error that tells the agent to back off.

File retention

Uploaded sources and converted results are stored temporarily. By default a result is downloadable for about one hour after the job completes. If your workflow needs longer, the REST API lets you extend the retention of a specific file up to 14 days with PUT /api/file/v1/file/uid/{uid}/retention and a body of {"retention_days": N}. Files are deleted automatically when their retention expires; nothing is kept indefinitely.

Getting an API key

Keys are bound to your file-convert.online account and can be created and revoked at any time. The easiest way is the account page: sign in, open file-convert.online/account/api-keys, click Create key, and copy the key together with a ready-made client snippet. The same can be done from a terminal with a signed-in session:

# 1. Sign in (or use the account you created on file-convert.online)
curl -s https://file-convert.online/api/identity/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"your-password"}'
# -> data.access_token

# 2. Create a key with that token (shown once - store it)
curl -s -X POST https://file-convert.online/api/identity/v1/api-keys \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"label":"my-agent"}'
# -> data.key = fc_live_...

The key is shown exactly once. Store it in your client's secret store or an environment variable, never in a shared config file. Revoking a key takes effect within a minute.

Client setup

Claude Code:

claude mcp add --transport http fileconvert https://file-convert.online/api/mcp/v1/mcp \
  --header "Authorization: Bearer fc_live_YOUR_KEY"

Cursor and any client that reads an mcpServers JSON block:

{
  "mcpServers": {
    "fileconvert": {
      "url": "https://file-convert.online/api/mcp/v1/mcp",
      "headers": { "Authorization": "Bearer fc_live_YOUR_KEY" }
    }
  }
}

Claude Desktop needs the mcp-remote shim to add a header to a remote server:

{
  "mcpServers": {
    "fileconvert": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://file-convert.online/api/mcp/v1/mcp",
        "--header",
        "Authorization:Bearer ${FC_API_KEY}"
      ],
      "env": { "FC_API_KEY": "fc_live_YOUR_KEY" }
    }
  }
}

VS Code (Copilot agent mode), in .vscode/mcp.json:

{
  "servers": {
    "fileconvert": {
      "type": "http",
      "url": "https://file-convert.online/api/mcp/v1/mcp",
      "headers": { "Authorization": "Bearer ${input:fc_api_key}" }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "fc_api_key",
      "description": "file-convert.online API key",
      "password": true
    }
  ]
}

n8n: add an MCP Client Tool node, set the endpoint to the URL above, choose the HTTP Streamable transport and Bearer authentication with your key. Full client walkthroughs are in the article at file-convert.online/blog/add-file-conversion-mcp-server-to-claude-cursor-vscode.

Security

  • Keys are stored hashed (SHA-256); the plaintext exists only in the creation response.
  • The MCP server never stores your key. It forwards it on every call to the same gateway the website uses, which verifies it, resolves your account and applies rate limits.
  • convert_file only fetches public http(s) URLs. Private, loopback, link-local and cloud-metadata addresses are refused, DNS answers are pinned for the request, redirects are re-checked hop by hop, and downloads are capped at 200 MiB.
  • Files are private to your account and deleted when retention expires.

Errors an agent will see

  • 401 from the gateway: the key is missing, invalid, expired or revoked. Create a new key.
  • No credits: the tool explains the cost, points to the pricing page and suggests get_balance.
  • Unknown or foreign job_id: the tool says so instead of relaying a raw server error.
  • Unsupported or mismatched formats: the tool lists the closest matches or the categories involved so the agent can correct itself without another round trip.

Status, versioning and support

The server reports its name and version on initialize (fileconvert-mcp). Tools are added, never renamed, within a major version. Questions and problems: file-convert.online/contact.

Ready to Convert Your Files?

Try our free online file converter. No registration required.

Start Converting