Troubleshooting & FAQ Leave feedback

Solutions to the most common GroupDocs.Watermark MCP server issues — server not appearing in the client, startup failures, missing native dependencies, and first-launch timeouts.

Note

Platform-specific troubleshooting: runtime problems depend on which build you run. For the dnx runner, native graphics libraries, and the Docker channel, see Troubleshooting (.NET). The issues on this page apply to every platform.

1. Restart the client — every client reads its MCP config only at startup.
2. Check the config file location for your OS (per-client reference) and that the entry sits under the right root key (mcpServers for Claude Desktop/Cursor/Windsurf, servers for VS Code/VS 2022).
3. Validate the JSON — a trailing comma silently breaks the whole file. If you used the installer, a timestamped .bak of your previous config sits next to the file for comparison.

A cold cache: on the very first use the server’s package or image is still downloading while the client is already waiting on the connection. Warming it once fixes it for good — the exact command depends on your build: .NET.

These are properties of the build you run rather than of MCP, so the fixes live with the platform:

Pass the file name, not a full path from your machine: the server resolves names inside its configured storage folder. When a name is not found the tool responds with the list of files it can see, so the agent can correct itself — check that list against GROUPDOCS_MCP_STORAGE_PATH.

It removes watermarks the engine can identify as watermark objects — including ones added by this or other GroupDocs tools, and many produced by common applications. A “watermark” that was flattened into the page image, or that is simply text drawn into the content, is not a separable object and will not come out. search_watermarks tells you which case you are in before you promise anyone a clean copy.

No. It is a deterrent and a provenance mark — visible, removable by someone determined, and no barrier to copying the text underneath. For confidentiality, control access to the file; for tamper-evidence, use a digital signature; for permanently removing content, use redaction.

A new one. Adding writes a watermarked copy; removing writes <name>_unwatermarked.<ext>. Your original is never modified — so in a chain (watermark, then something else) the agent must pass the produced file forward.

Yes — PDF, Office formats, and image formats are all supported targets, and an image watermark can be a PNG, JPG, or similar. Details: Supported formats.

The MCP tools expose text, font size, rotation, and opacity (for image watermarks). Fine-grained positioning and per-section placement are library-level features not surfaced as tool parameters today; if you need them through MCP, say so in the forum.

Ask your agent “list your GroupDocs watermark tools and the license status” — it should name add_watermark, add_image_watermark, search_watermarks, remove_watermarks, get_document_info, get_license_status. For a scripted check that performs the real MCP handshake and a live call through the engine, see verifying a .NET installation.

Post your config (redact license paths) and the client name in the Watermark forum — we answer MCP questions daily. Bugs: GitHub issues.