--- seo_title: MCP Server JSON Config: Claude Code, Cursor Setup | EnConvert meta_desc: Set up the @enconvert/mcp server in Claude Code, Cursor, Windsurf, and Claude Desktop with exact JSON config or one command: npx @enconvert/mcp setup. keywords: how to configure mcp server json, mcp server file conversion, claude code mcp server setup, cursor mcp json config, claude desktop mcp server install, windsurf mcp config, npx mcp server setup, model context protocol file converter, enconvert mcp server, mcp image compression tool, mcp pdf to markdown for rag --- # 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.
npm: @enconvert/mcp · Source: enconvert/mcp · Node: 18+ · Transport: stdio
--- ## What is MCP? The [Model Context Protocol](https://modelcontextprotocol.io) 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](/docs/sdks/nodejs). 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](/dashboard) --- ## Install: one command ```bash 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. ```text $ 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. ```
Restart required. MCP servers only load when an assistant session starts. After setup, fully exit the assistant and reopen it before testing.
### Manage it just as easily | Command | What it does | |---------|-------------| | `npx @enconvert/mcp status` | Shows where the server is installed and validates your key live | | `npx @enconvert/mcp rotate-key` | Replaces the stored API key with one command, applied to every client | | `npx @enconvert/mcp remove` | Uninstalls from selected tools (optionally deletes the saved key) | | `npx @enconvert/mcp setup --yes` | Non-interactive: configures all detected tools with the saved key | | `npx @enconvert/mcp upgrade` | Checks npm for a newer version and upgrades it. Add `--dry-run` to preview | 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`, ...): ```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: ```bash 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 | Purpose | |------|---------| | `perceive_url` | Render a live page into multiple artifacts at once: markdown (inlined), HTML, screenshots, PDF, links, images, plus structured extraction, with ~1h caching | | `get_perceive_operation` / `perceive_batch` / `get_perceive_batch` | Re-sign artifact URLs; render up to 1000 URLs in one batch; poll batches | | `discover_urls` | Enumerate a site's URLs via sitemap/crawl/hybrid, with no rendering | | `web_search` | Google-backed search in six categories, with optional auto-render of top results | | `extract_structured` | Schema-driven data extraction (free CSS pass + LLM escalation) from up to 50 URLs | | `start_ingest` + job tools | Turn a site or URL list into RAG-ready chunked JSONL (async), with list/get/cancel/webhook-retry | | `create_watcher` + watcher tools | Monitor pages for changes on an hourly-plus cadence, with diff history, list/get/update/delete | | `convert_document` | Convert DOCX, XLSX, PPTX, ODT, Pages, Numbers, HTML, Markdown, CSV, JSON, XML, YAML, TOML between formats (PDF by default) | | `convert_image` | Convert between JPEG, PNG, SVG, HEIC, WebP, plus PDF → JPEG rasterization, with optional `width` and `height` to size the canvas when rasterizing SVG | | `compress_image` | Shrink a PNG, JPEG, or WebP in place, format unchanged, optionally down to a target size in KB | | `convert_anything_to_markdown` | Turn PDF, Office, ODF, EPUB, HTML, CSV, or text files into clean heading-aware Markdown for RAG pipelines | | `convert_anything_to_pdf` | Turn almost any file into a PDF: Office, ODF, iWork, images, SVG, HTML, Markdown, EPUB, RTF, CSV, plus PDF passthrough | | `get_job_status` | Check a file-conversion job by its job ID | 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` | Setting | Required | Default | Purpose | |----------|----------|---------|---------| | `ENCONVERT_API_KEY` (env) or `api_key` (config file) | Yes | -- | Private API key (`sk_live_...`) | | `ENCONVERT_BASE_URL` (env) or `base_url` (config file) | No | `https://api.enconvert.com` | Override for staging or self-hosted gateways |
Never paste a key into the assistant chat. Use npx @enconvert/mcp setup (hidden input), or set it via the env block in the MCP config file. Keys committed to chat history end up in transcripts.
--- ## Example prompts Once installed, try these in a fresh assistant session: ```text Give me https://en.wikipedia.org/wiki/Model_Context_Protocol as markdown and summarize it. ``` ```text Screenshot https://news.ycombinator.com and save the page as a PDF too. ``` ```text Search for the three best static site generators and read their homepages. ``` ```text Get every plan name and price from https://example.com/pricing. ``` ```text Convert /Users/me/Desktop/report.docx to PDF. ``` ```text Squeeze /Users/me/Desktop/screenshot.png under 200 KB without changing the format. ``` ```text Turn /Users/me/Downloads/whitepaper.pdf into Markdown for my RAG index. ``` ```text 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](/docs/sdks/nodejs). 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](https://www.npmjs.com/package/@enconvert/mcp) - **GitHub**: [enconvert/mcp](https://github.com/enconvert/mcp) - **License**: MIT - **Underlying SDK**: [Node.js SDK](/docs/sdks/nodejs) - **MCP specification**: [modelcontextprotocol.io](https://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.