MCP Server Setup and JSON Configuration#

@enconvert/mcp is the official Model Context Protocol (MCP) server for EnConvert. It lets any MCP-compatible AI assistant (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code, Zed, Gemini CLI, Codex, OpenCode) render, search, extract, ingest, watch, convert, and compress web pages and files directly from the chat. Configure it with a single command, npx @enconvert/mcp setup, or copy the exact JSON config block for your client's MCP config file. It runs locally over stdio on Node.js 18+ and registers twenty-four tools.

What is MCP?#

The Model Context Protocol is an open standard for exposing tools, prompts, and resources to LLM-powered assistants over a small JSON-RPC interface. An MCP server runs as a local subprocess, the assistant launches it on session start, and the tools become first-class capabilities the model can invoke during a conversation.

@enconvert/mcp is a thin wrapper around the Node.js SDK. It registers twenty-four tools, each with a description tuned for reliable LLM tool selection. All HTTP, authentication, timeout, and recovery polling are inherited from the SDK.

Requirements#

• Node.js 18 or later on the machine running the assistant
• An EnConvert private API key (sk_live_...), which you generate in the dashboard

Install: one command#

npx @enconvert/mcp setup

The interactive wizard does everything:

1. Detects your AI tools (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Zed, Gemini CLI, Codex CLI, OpenCode) and lets you pick which ones get EnConvert (detected tools are preselected).
2. Asks for your secret API key once (hidden input) and validates it live against the API. Pasted a public key by mistake? It tells you exactly that.
3. Writes every config correctly, including the cmd /c npx wrapper that native Windows requires.

$ npx @enconvert/mcp setup

  EnConvert MCP - setup

? Which AI tools should get EnConvert?
  [x] Claude Code (detected)    [x] Cursor (detected)
  [ ] Claude Desktop            [ ] Windsurf   ...
? Paste your SECRET API key (sk_live_..., input hidden): ********
  ✔ API key is valid.
  + Claude Code - claude CLI (user scope)
  + Cursor - ~/.cursor/mcp.json

  Done. Restart your AI tools to pick up the server.

Manage it just as easily#

For scripting, setup --clients claude-code,cursor --api-key sk_live_... --yes skips every prompt. Running rotate-key without an argument prompts with hidden input, so the key never lands in your shell history.

Where the key lives#

setup stores your key once in ~/.enconvert/config.json (file mode 600) instead of duplicating it across every client's plaintext config. The server reads it at startup; the ENCONVERT_API_KEY environment variable always overrides it (for Docker, CI, or manual setups). Rotating a key is therefore a single-file change, and every client picks it up on its next launch.

Advanced: manual configuration#

Prefer to wire it yourself? Add this to your client's MCP config (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, Claude Desktop's claude_desktop_config.json, ...):

{
  "mcpServers": {
    "enconvert": {
      "command": "npx",
      "args": ["-y", "@enconvert/mcp@latest"],
      "env": {
        "ENCONVERT_API_KEY": "sk_live_your_key"
      }
    }
  }
}

On native Windows, replace command with cmd and prepend "/c", "npx" to args, because bare npx hangs. For Claude Code:

claude mcp add enconvert -s user \
  -e ENCONVERT_API_KEY=sk_live_your_key \
  -- npx -y @enconvert/mcp@latest

The inline env block is optional if you have run setup, since the server falls back to the saved key automatically.

Available tools#

Twenty-four tools. All URL/browser work goes through the V2 tools (perceive_url and friends); the file tools cover local and remote document, image, and compression work.

Tool descriptions follow a consistent Use when / Do NOT use when / Returns structure so the assistant routes prompts to the right tool. The V2 tools require the private API key and are plan-gated, so a disabled feature or exhausted quota returns a clear quota message, not a cryptic error.

Two behaviours are worth knowing before you prompt for them. compress_image never changes the format (a PNG comes back a PNG, a JPEG comes back a JPEG) and never returns a file larger than the input, so it is safe to run on an already-optimized file; target_size_kb is best effort, and a budget that cannot be reached returns the smallest file achieved rather than an error, so check the file size that comes back. On convert_image, width and height apply to SVG input only and accept 1 to 10000 each: passing one alone scales the output proportionally from the SVG's own aspect ratio, while passing both sets the exact canvas.

Configuration#

The API key is resolved in this order:

1. ENCONVERT_API_KEY environment variable (from the assistant's MCP config), which always wins
2. ~/.enconvert/config.json, written by npx @enconvert/mcp setup

Example prompts#

Once installed, try these in a fresh assistant session:

Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it.

Screenshot https://news.ycombinator.com and save the page as a PDF too.

Search for the three best static site generators and read their homepages.

Get every plan name and price from https://example.com/pricing.

Convert /Users/me/Desktop/report.docx to PDF.

Squeeze /Users/me/Desktop/screenshot.png under 200 KB without changing the format.

Turn /Users/me/Downloads/whitepaper.pdf into Markdown for my RAG index.

Watch https://example.com/changelog and tell me when it changes.

The assistant picks the right tool automatically: URL work lands on perceive_url, search on web_search, structured scraping on extract_structured, size budgets on compress_image, RAG-ready Markdown on convert_anything_to_markdown, and the rest of the file work on the convert tools.

Output shape#

Every tool returns a consistent response:

• A text summary with download URLs and metadata
• A structuredContent block with the full typed result
• A resource_link to the local file when save_to is provided (file tools)
• For perceive_url, the markdown artifact is also inlined in the response (up to ~256 KB), so the assistant can read and summarize without a separate fetch

How it works#

@enconvert/mcp calls the same public REST endpoints documented in the rest of this site, through the Node.js SDK. That means:

• Same wire format: every tool maps 1:1 to a /v1/convert/* or /v2/* endpoint
• Same timeout recovery: long conversions automatically fall back to job_id polling, transparently
• Same authentication: your private API key authorizes every call, and your dashboard quota and rate limits apply

The assistant never sees the API key. It only sees the tool list and tool inputs.

Troubleshooting#

Assistant tries to use a local browser instead of the MCP tool. The MCP server is not registered or did not start. Run npx @enconvert/mcp status in a regular terminal, then restart the assistant.

Authentication failed: Invalid or missing API key. Run npx @enconvert/mcp status, which shows where the key comes from and validates it live. Fix it with npx @enconvert/mcp rotate-key.

npx hangs on native Windows. Use cmd /c npx .... npx @enconvert/mcp setup writes this wrapper automatically on Windows.

Tool call times out before the conversion finishes. Heavy browser renders may take 30+ seconds. The SDK waits up to 5 minutes by default; raise the assistant's per-tool timeout if it cuts off sooner.

Relative path rejected on convert_document / convert_image. Pass an absolute path (e.g., /Users/me/file.docx or C:\Users\me\file.docx), or pass an http(s):// URL. MCP servers have no reliable working directory.

Source and links#

• npm: @enconvert/mcp
• GitHub: enconvert/mcp
• License: MIT
• Underlying SDK: Node.js SDK
• MCP specification: modelcontextprotocol.io

Frequently asked questions#

How do I configure an MCP server in JSON?#

Add an entry under mcpServers in your client's MCP config file (~/.cursor/mcp.json for Cursor, ~/.codeium/windsurf/mcp_config.json for Windsurf, claude_desktop_config.json for Claude Desktop) with "command": "npx", "args": ["-y", "@enconvert/mcp@latest"], and your ENCONVERT_API_KEY in the env block. Or skip manual JSON entirely: npx @enconvert/mcp setup detects your installed AI tools and writes every config correctly.

How do I set up an MCP server in Claude Code?#

Run claude mcp add enconvert -s user -e ENCONVERT_API_KEY=sk_live_your_key -- npx -y @enconvert/mcp@latest, or use the interactive wizard npx @enconvert/mcp setup, which detects Claude Code and configures it automatically. Fully restart the assistant afterwards, because MCP servers only load when a session starts.

Why does npx hang when starting an MCP server on Windows?#

Bare npx hangs on native Windows. Replace command with cmd and prepend "/c", "npx" to args; npx @enconvert/mcp setup writes this wrapper automatically on Windows.

Where does the MCP server store my API key?#

npx @enconvert/mcp setup stores the key once in ~/.enconvert/config.json (file mode 600) instead of duplicating it across every client's plaintext config. The ENCONVERT_API_KEY environment variable always overrides it, and npx @enconvert/mcp rotate-key replaces the stored key for every client in one command.

Can an AI assistant convert files through an MCP server?#

Yes. The convert_document tool converts DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML, and TOML between formats (PDF by default). EPUB has no convert_document pair; send .epub files through convert_anything_to_pdf or convert_anything_to_markdown. In addition, convert_image converts between JPEG, PNG, SVG, HEIC, and WebP, plus PDF to JPEG rasterization. Pass absolute file paths or http(s):// URLs, since MCP servers have no reliable working directory.

How do I shrink an image without changing its format?#

Ask the assistant to compress the file and it routes to compress_image, which keeps a PNG a PNG, a JPEG a JPEG, and a WebP a WebP. It strips metadata while preserving the ICC profile and EXIF orientation, and never returns a file larger than the input. Add a target_size_kb budget and it downscales with the aspect ratio locked until the budget is met; an unreachable budget returns the smallest file achieved rather than an error, so check the size that comes back.