Troubleshooting & FAQ Leave feedback
On this page
Solutions to the most common GroupDocs.Search MCP server issues — server not appearing in the client, startup failures, missing native dependencies, and first-launch timeouts.
NotePlatform-specific troubleshooting: this product runs as a Docker container, so runtime problems are Docker problems — the daemon, volume mounts, file ownership on Linux, and the first image pull. See Troubleshooting (.NET). The issues on this page apply to every platform.
- Restart the client — every client reads its MCP config only at startup.
- Check the config file location for your OS (per-client reference) and that the entry sits under the right root key (
mcpServersfor Claude Desktop/Cursor/Windsurf,serversfor VS Code/VS 2022). - Validate the JSON — a trailing comma silently breaks the whole file. If you used the installer, a timestamped
.bakof 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:
| Symptom | Where the fix is |
|---|---|
| “docker daemon not reachable” | .NET troubleshooting — start Docker Desktop or dockerd |
| “The index folder … is not writable” (Linux) | .NET troubleshooting — run the container with --user |
| The index is empty after a restart | .NET troubleshooting — /data is not a mounted volume |
You were told to run dnx | There is no NuGet package for this product — why |
Pass a path relative to the storage folder — contracts or contracts/lease.pdf, not /home/me/contracts. When a path is not found the tool answers with the folder’s contents, so the agent can correct itself. In Docker the storage folder is whatever you mounted at /data (configuration).
Because unquoted words separated by spaces do not match in GroupDocs.Search. Quote the phrase — "termination penalty" — or join the words with AND. The server spots this and adds a hint to the empty result, so an agent usually corrects itself on the next call:
"hint": "Unquoted words separated by spaces do not match. Search the phrase
as \"termination penalty\", or combine the words with AND / OR,
e.g. termination AND penalty."
The engine indexes each file’s creation and modification dates as fields, and a bare daterange(…) searches them too. Write content: daterange(2026-07-01 ~~ 2026-09-30) to search dates written in the documents — find documents by date and amount.
The engine removes paths that were added, not files inside an added folder. If you indexed contracts, removing contracts/old.pdf fails with an explanation; remove contracts and add back what you want, or index sub-folders separately when you expect to remove them — keep an index current.
In /data/.groupdocs-search-index/<name> — inside the mounted documents folder — so it survives --rm and the next container finds it. With read-only documents, mount a writable folder at /index and set GROUPDOCS_MCP_INDEX_PATH=/index (configuration). If you are not mounting /data at all, the index lives inside the container and disappears with it.
No. It is full-text search: words, phrases, boolean operators, fuzzy matching, ? wildcards, regular expressions, date and number ranges. It does not match meaning — the agent compensates by trying synonyms and variants (renewal OR renews, fuzzy: true), which works well for document questions that use the words the documents use, and poorly for purely conceptual ones. There are no embeddings, no model calls, and no vector database involved.
No. A scan without a text layer is indexed by its file properties only; its words are pixels. Run OCR first if you need scans in the index.
Because there is no NuGet package. The packed tool is 280.9 MiB — the engine alone is about 200 MiB with its ONNX and SkiaSharp natives — which is over nuget.org’s 250 MB limit, so this product ships via Docker only. See MCP server for .NET.
GroupDocs.Parser reads one document you name. Search answers which documents, across a folder, and quotes the passages. Pipelines often use both: Search to find the three files that matter, Parser to pull a table out of one of them.
Ask your agent “list your GroupDocs search tools and the license status” — it should name add_to_index, search, get_text_fragments, update_index, remove_from_index, get_index_info, create_index, 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 Search forum — we answer MCP questions daily. Bugs: GitHub issues.
Was this page helpful?
Any additional feedback you'd like to share with us?
Please tell us how we can improve this page.
Thank you for your feedback!
We value your opinion. Your feedback will help us improve our documentation.
