Troubleshooting & FAQ Leave feedback

Solutions to the most common GroupDocs.Markdown 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.

Evaluation mode processes only the first three pages. This is the single most important thing to know about this server, because the output looks perfectly valid — it is simply missing almost everything. Check get_license_status before any ingestion run; see Licensing.

images: "base64" (the default) embeds pictures as data URIs, so the .md is self-contained — good for pasting into a chat or storing a single artefact. images: "file" writes them alongside the .md — much better for a repository or a RAG index, where a multi-megabyte data URI in the middle of a chunk is noise. There is also an option to skip images entirely when only the text matters.

They overlap. GroupDocs.Conversion converts between 100+ formats, Markdown among them. This server is specialised for Markdown: it exposes the dialect (github or commonmark), image handling, page selection, and YAML front matter as first-class options. If Markdown is the destination and the details matter, use this one.

No. Conversion works on the text layer; a scanned, image-only PDF produces images rather than recognised text. The same is true across GroupDocs MCP servers — none of them include OCR today.

frontMatter: true prepends YAML with title, author, format, and page count. Static site generators consume it directly, and RAG pipelines can use it as chunk metadata rather than re-deriving the source from a file path.

Ask your agent “list your GroupDocs Markdown conversion tools and the license status” — it should name convert_to_markdown, 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 Markdown forum — we answer MCP questions daily. Bugs: GitHub issues.