MCP server

Let your AI assistant watermark files, detect watermarks and manage assets through the Etchv API. MCP (Model Context Protocol) is a standard way for assistants to use outside tools. The open-source MCP server runs on your computer over stdio (standard input and output).

Install and connect

You need Node.js 24+, an API key, a local media folder and an MCP client that can start local servers.

Add this to your client’s configuration. Create the folder first and replace the absolute path. Supply your key through your client's secure configuration.

{
  "mcpServers": {
    "etchv": {
      "command": "npx",
      "args": ["-y", "@etchv-labs/mcp-server@1"],
      "env": {
        "ETCHV_API_KEY": "YOUR_ETCHV_API_KEY",
        "ETCHV_FILES_ROOT": "/absolute/path/media"
      }
    }
  }
}

Restart your client, then ask it to run check_api_key. This check uses no credits. There is no hosted MCP URL, so clients that only support remote servers cannot connect.

claude mcp add etchv --env ETCHV_API_KEY=YOUR_ETCHV_API_KEY \
  --env ETCHV_FILES_ROOT=/absolute/path/media -- npx -y @etchv-labs/mcp-server@1

codex mcp add etchv --env ETCHV_API_KEY=YOUR_ETCHV_API_KEY \
  --env ETCHV_FILES_ROOT=/absolute/path/media -- npx -y @etchv-labs/mcp-server@1

What you can ask

• “Watermark this PDF for delivery-42, keeping its text selectable.”
• “Check this video for an Etchv watermark.”
• “List my latest watermarked assets and download the one I choose.”
• “Share the board pack with alex@example.com and sam@example.com so each gets their own copy, then tell me who has opened it.”
• “Watermark every PDF in contracts/ with the file name as the recipient and save the results to delivered/.”

Your first watermark

Put photo.jpg in the media folder, then ask:

Watermark photo.jpg for delivery-42. Save photo-watermarked.jpg, then detect its watermark.

The assistant calls watermark_media with a non-empty data object and an idempotency_key that stays the same on retries. It collects the result with get_job and get_job_result, using operation: "embed" and an output_path. Detection uses detect_media and operation: "detect".

Detection returns the watermark ID, a digest (fixed-length fingerprint) of your data. It does not return the original JSON. Keep your source record in your own system.

Many files at once

watermark_batch watermarks up to 100 files in one batch, each with its own data. Name the files with input_paths, with input_dir and an optional glob such as "*.pdf" (no braces or ..), or with items that carry their own data. A data_template fills in the rest: string values may use {filename}, {stem} (the name without its extension) and {index} (the file's 0-based position).

Batches take images, PDF, DOCX and PPTX documents, and videos.

The server uploads each file once and starts the batch. With wait: true it checks progress at the pace the API asks for, for up to wait_seconds (10 minutes by default), and with output_dir it saves the results. Clients that ask for progress see each upload and check; keep wait_seconds below your client's tool timeout.

Otherwise the assistant follows the batch with get_batch and collects it with download_batch. It saves each successful file under the name it has in the batch zip, such as 001-contract-acme-watermarked.pdf, or the zip itself when the batch was created with archive: true. Failed items are listed with their error codes.

Each file costs the same credits as a single request, and files that fail are refunded. Calling watermark_batch again with the same arguments resumes or returns the same batch instead of a new one. If that batch expired before it started, or finished and its results expired after 24 hours, the tool says so; pass a new idempotency_key to run the files again. More than 100 files are refused before anything is sent; split them into several batches.

Sync or async

After a timeout, reuse the same idempotency key (a value you choose so a retry isn't run twice). Accepted jobs keep running. The server does not keep checking for results forever. See job handling.

Supported media

Detection takes delivered files up to 192 MiB for images, 95 MiB for PDFs and 100 MiB for DOCX, PPTX and video. Files over 40 MiB are sent as a large-file upload automatically; set ETCHV_LARGE_FILE_THRESHOLD (bytes) to change that. Image and document detection above 95 MiB returns a job receipt for get_job_result.

API limits and plan access still apply. Downloads can be up to 512 MiB and 10 minutes. The API must start responding within 45 seconds. Embedding and detection use normal API credits.

Tools and permissions

Turn on only the scopes you need. Your MCP client decides when to ask you to approve paid operations and changes. Read etchv://capabilities inside the assistant for help with the tools.

Storage and webhooks

Storage credentials and signing secrets stay out of tool arguments and responses.

File handling

Files must stay inside ETCHV_FILES_ROOT. Paths that climb out of it (../) and symlinks are rejected. Output folders must already exist, and files are never overwritten. Use a separate folder that you control.

Input files go to the Etchv API. Results stay on your disk. The assistant only gets file paths and checksums. Treat asset names and metadata as data, not instructions.