Skip to main content

Conversion Service MCP server

The Conversion Service MCP server is a built-in interface that lets AI agents drive the service through the Model Context Protocol (MCP). It runs on the Conversion Service Advanced API so that an agent can use the Conversion Service features: convert documents with any configured workflow and profile, combine PDFs into dossiers, and read service status, workflows, and statistics.

The endpoint is available whenever Conversion Service is running. It has no authentication and is intended for intranet use only, so connect from an MCP client on the same trusted network.

Endpoint​

The MCP server uses the following connection settings:

  • Transport: streamable HTTP
  • Path: /mcp (fixed)
  • Default endpoint: http://localhost:13033/mcp
  • Host and port: the same as the Advanced API base URL. A service reachable at http://HOST_ADDRESS:PORT/conversion/v1.0/rest serves MCP at http://HOST_ADDRESS:PORT/mcp.

Connect a client​

Before connecting, confirm Conversion Service is running and its endpoint is reachable from the machine that runs the client. The server uses the streamable HTTP transport, so any MCP client that supports remote HTTP servers can connect.

note

Cloud-based AI connectors, such as the custom connectors in Claude, aren’t supported. Conversion Service runs on a local or private network, so a cloud service can’t reach its MCP endpoint. Connect from an MCP client on the same network.

Replace localhost in the following examples with the service host when the client runs on another machine on the network.

Claude Code​

Add the server with Claude Code:

claude mcp add --transport http convsrv http://localhost:13033/mcp

Or add it to a project’s .mcp.json:

{
  "mcpServers": {
    "convsrv": {
      "type": "http",
      "url": "http://localhost:13033/mcp"
    }
  }
}

For more details, refer to the Claude Code MCP documentation.

Claude Desktop​

Claude Desktop connects only to local stdio servers, so bridge it to the endpoint with the mcp-remote proxy. Add the server to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "convsrv": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:13033/mcp", "--allow-http"]
    }
  }
}

The configuration file is at %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. The npx command requires Node.js on the client machine, and the --allow-http flag lets mcp-remote reach the service’s plain-HTTP endpoint, which is safe on the trusted intranet. Claude Desktop’s Add custom connector option requires an internet-reachable HTTPS server, so use this stdio bridge instead.

Codex CLI​

Add the server to ~/.codex/config.toml:

[mcp_servers.convsrv]
url = "http://localhost:13033/mcp"

For more details, refer to the Codex MCP documentation.

Other clients​

Most MCP clients accept a server name and the streamable HTTP URL: point the client at the endpoint. A client that supports only local stdio servers needs the mcp-remote bridge shown in the Claude Desktop section, including its --allow-http flag.

Verify the connection​

After connecting, the client lists the server’s tools and prompts. To confirm the connection, ask the client to list the conversion workflows, which calls list_workflows. A successful response returns the workflows and profiles configured on the service.

If the client can’t connect, check that the host and port match the endpoint and that no firewall blocks the listener. If a tool returns a service_unreachable error instead, Conversion Service didn’t respond; a service that just started might still be initializing.

Tools​

The server provides five tools:

  • convert_document: Convert one document to PDF, PDF/A, TIFF, signed PDF, or another format defined by the chosen workflow.
  • create_dossier: Combine several PDFs into a single dossier PDF with a table of contents.
  • list_workflows: List the workflows configured on the service and their profiles. Read-only.
  • get_service_status: Return a health snapshot of the service: version, status, start time, worker process count, queue length, and job counts. Read-only.
  • get_statistics: Return service utilization over a recent time window. Read-only.

The read-only tools require no arguments to call, and the connected client lists each tool’s full parameter schema. The two tools that write files take these parameters.

Convert a document​

Convert a single input file to the format defined by the chosen workflow.

  • input: A file path or URL to an Office, PDF, image, email, HTML, text, or ZIP file. Refer to Input files.
  • workflow and profile: Service-configurable and case-sensitive. Call list_workflows to discover the valid values, or omit both for the service defaults. The workflow sets the output format, for example Conversion (PDF), Archive PDF/A-2 (PDF/A), Archive TIFF (TIFF), or Sign (signed PDF). Refer to Workflows.
  • output_path: A directory or full file path for the result. Defaults to the service’s Documents folder. Existing files are never overwritten; the server adds a numeric suffix instead.

Combine PDFs into a dossier​

Combine up to 50 PDFs into one dossier PDF, preserving input order.

  • inputs: Up to 50 PDFs, in order. All must already be PDFs, so convert other formats with convert_document first.
  • profile: The default Dossier profile generates a table of contents and appends each input in turn. Refer to the Dossier workflow.

Prompts​

The server provides prompts that wrap common tasks. Clients that surface prompts as slash commands list them by name:

  • convert_to_pdf: Convert a single document to plain PDF. Takes a file path or URL.
  • convert_to_pdfa: Convert a single document to archival PDF/A. Takes a file path or URL, and an optional PDF/A version (1, 2, or 3; defaults to 2).
  • combine_pdfs: Combine several PDFs into one dossier PDF with a table of contents. Takes the PDFs to combine, in order.

Input files​

The convert_document and create_dossier tools accept two kinds of input:

  • An HTTP or HTTPS URL. The service fetches the file.
  • An absolute local file path. The service reads the file from its own filesystem.

A local path must be absolute and point to a file that the service process can read. Local input files are limited to 500 MB by default, which an operator can raise with the SERVICE__MCP__MAXINPUTFILEBYTES setting.

note

When the service runs in a container, a local path resolves only if the file is in a folder mounted into the container. Otherwise, copy the file into a mounted folder, or pass a URL. Refer to Local file access in containers.

Local file access in containers​

A containerized service can only read and write files in folders that are mounted into the container. To let the MCP tools work with local file paths, bind-mount a host directory into the container and point the server at it with the SERVICE__MCP__HOSTHOME setting.

The server then maps paths automatically. An input path under the shared host directory, such as C:\Users\USER_NAME\report.docx, is rewritten to its location inside the container before the service reads it. Output paths are mapped the same way, and the default output location is the Documents folder inside the shared directory. Paths that resolve outside the mount are rejected, so a tool can’t reach files beyond the shared folder.

To enable local file access with Docker Compose:

  1. In docker-compose.env, set MCP_HOST_HOME to the host directory to share, for example C:\Users\USER_NAME on Windows or /Users/USER_NAME on macOS.
  2. In docker-compose.yaml, uncomment the ${MCP_HOST_HOME}:/host volume mount and the SERVICE__MCP__HOSTHOME environment variable. The container mount target /host is fixed, so set only the host side.
  3. Restart the service.

Agents then pass ordinary host paths under the shared directory, and the service reads and writes them inside the container.

On a native installation, the service shares the caller’s filesystem, so no mount or configuration is needed and paths are used as-is.

Error responses​

When a tool rejects its input or can’t reach the service, it returns a JSON envelope instead of breaking the connection:

{
  "success": false,
  "error": {
    "code": "file_not_found",
    "message": "Input file not found: ...",
    "hint": "..."
  }
}

The code field is a stable identifier. Common codes:

  • invalid_arguments: An argument is missing or malformed, for example a relative input path.
  • file_not_found: The service can’t find the local input file.
  • access_denied: The service can’t read the local input file because of filesystem permissions.
  • file_too_large: The input file exceeds the 500 MB size limit.
  • too_many_inputs: A create_dossier call passed more than 50 inputs.
  • service_unreachable: Conversion Service didn’t respond. A service that just started might still be initializing.
  • timeout: The conversion didn’t finish in the time the server waits for a result. Retry the request.
  • conversion_failed: The conversion failed unexpectedly. Review the service log for details.

These codes cover input and connection problems. When the conversion itself fails, the envelope instead returns the service’s own error details and processing events, without a code. Inspect those to diagnose the failure.

Security​

caution

The MCP endpoint shares its listener with the Advanced API and applies no authentication. Like the REST API, it’s designed for use in a protected intranet only. Restrict access with a firewall, and don’t expose the listener to untrusted networks. For more details, review API security.

The server exposes all five tools to every connected client and has no per-tool access control. The read-only tools (list_workflows, get_service_status, and get_statistics) can’t change anything, but convert_document and create_dossier read and write files on the service’s filesystem. Control who can reach the endpoint at the network level.

Local inputs and outputs stay on the service host, but a URL input is fetched by the service itself, so it can reach any address the host can. The server runs whatever a connected agent asks. An agent handling untrusted content could be steered by prompt injection into converting unintended files or reaching internal URLs. Connect only trusted clients, run the service under a least-privilege account, and restrict its outbound network access when inputs might be untrusted.