MCP Server

Official Model Context Protocol (MCP) server for Enconvert. Drop the conversion API into any MCP-compatible AI assistant — Claude Code, Cursor, Windsurf, Claude Desktop, Continue, and others — so the agent can convert URLs, documents, and images directly from the chat.

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 five conversion 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_...) — generate one in the dashboard

Install

The server runs through npx — no local install required. Pick the recipe for your assistant.

Claude Code (CLI, macOS / Linux)

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

Claude Code (CLI, native Windows)

Native Windows requires wrapping npx in cmd /c — without it the command hangs.

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

WSL users follow the macOS/Linux recipe above.

Cursor

Edit ~/.cursor/mcp.json (create the file if it does not exist):

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

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json. Same JSON shape as Cursor. Use the Windows variant on native Windows.

Claude Desktop

Edit claude_desktop_config.json:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

Same JSON shape as Cursor. Restart the application after editing.

Available tools

Tool descriptions follow a consistent Use when / Do NOT use when / Returns structure so the assistant routes prompts to the right tool. For example, "summarize this article" maps to convert_url_to_markdown — much cheaper on tokens than rendering a PDF or screenshot.

Each conversion returns a presigned download URL plus structured metadata (filename, file size, conversion time). When save_to is provided, the file is also streamed to that local path and surfaced as an inline resource link.

Configuration

All configuration is via environment variables passed through the assistant's MCP config.

Example prompts

Once installed, try these in a fresh assistant session — each maps to one tool:

Save https://en.wikipedia.org/wiki/PDF as a PDF.

Screenshot https://news.ycombinator.com for me.

Give me the article at https://en.wikipedia.org/wiki/Model_Context_Protocol
as markdown so we can summarize it.

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

Convert /Users/me/Desktop/iphone.heic to webp.

The assistant picks the right tool automatically. Disambiguation prompts like "summarize this article: \<url>" correctly route to convert_url_to_markdown rather than convert_url_to_pdf, because the descriptions explicitly steer text-extraction intents to the markdown tool.

Output shape

Every conversion tool returns a consistent response:

• A text summary containing the presigned download URL, filename, file size, and conversion time
• A structuredContent block with typed fields — presignedUrl, objectKey, filename, fileSize, conversionTimeSeconds, optional savedTo
• A resource_link to the local file when save_to is provided
• For convert_url_to_markdown, the extracted Markdown 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/* endpoint
• Same timeout recovery — long URL-to-PDF or large document conversions automatically fall back to job_id polling, transparently
• Same authentication — your private API key authorizes every conversion, and your dashboard quota and rate limits apply

The assistant never sees the API key directly. 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. In a regular terminal run claude mcp list (or check your assistant's MCP status panel). Restart the assistant after registering.

Authentication failed: Invalid or missing API key. The env var did not propagate. The assistant only sees env vars passed via -e or the env block in the config file — not your shell environment.

npx hangs on native Windows. Use cmd /c npx .... The cmd shim handles Windows path resolution that bare npx does not.

Tool call times out before the conversion finishes. Heavy URL-to-PDF or large document conversions 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/enconvert-mcp
• License — MIT
• Underlying SDK — Node.js SDK
• MCP specification — modelcontextprotocol.io