Powered by Zoomin Software. For more details please contactZoomin

MarkLogic MCP Server

Table of Contents

Tool contracts

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
Print
  • Last Updated: September 9, 2026
  • 2 minute read
    • Documentation

Input and output contracts for the three passthrough tools are exposed by the MarkLogic MCP server. These tools forward requests to the MarkLogic Retrieval API and return the endpoint response with minimal transformation.

Overview

The server exposes three tools:

Tool Internal module id Required argument Purpose
RetrieveDefinition retrieve-definition none Return the current /v1/retrieve/definition payload
Retrieve retrieve retrieveQuery Run /v1/retrieve with a JSON request body
Augment augment augmentRequest Run /v1/retrieve/augment with a JSON request body

General Contract

  • Tool arguments are passed as strings and parsed as JSON by the agent layer.
  • Missing required arguments return a tool error without calling MarkLogic.
  • Invalid JSON returns a tool error without calling MarkLogic.
  • MarkLogic Server errors are surfaced to the caller as tool errors.
  • Successful calls return a single text chunk with pretty-printed JSON from the underlying endpoint.

RetrieveDefinition

Purpose: Fetch the current search configuration for the deployment.

Arguments: none

Returns: the JSON payload returned by GET /v1/retrieve/definition.

Typical fields in the response include:

  • description
  • labels
  • filters
  • documentSchemas
  • vectorMetadata
  • metadataFields
  • recommendedWorkflow
  • queryFormat

Example

RetrieveDefinition()

Retrieve

Purpose: Run hybrid search against /v1/retrieve.

Required argument: retrieveQuery

retrieveQuery must be a JSON string representing the request body sent to /v1/retrieve.

Canonical request fields include:

  • text
  • labels
  • filters
  • vectors
  • metadata
  • entities
  • relations
  • topk

Example

{
  "retrieveQuery": "{\"text\":\"diabetes OR insulin\",\"topk\":10}"
}

Returns: the JSON payload returned by POST /v1/retrieve, typically including:

  • matches
  • totalMatches when text search is used
  • warnings when the request triggers non-fatal issues
  • mcpWarnings when MCP-side processing adds structured warnings

Augment

Purpose: Retrieve full document content by URI from /v1/retrieve/augment.

Required argument: augmentRequest

augmentRequest must be a JSON string representing the request body sent to /v1/retrieve/augment. The canonical field name is URIs (uppercase), though the agent normalizes lowercase uris to URIs before calling MarkLogic.

Canonical request fields include:

  • URIs — array of URI strings or {uri, xpath} objects
  • metadata — optional array containing metadata, processingMetadata, and/or provenance

Example

{
  "augmentRequest": "{\"URIs\":[\"/medical/doc001.json\"]}"
}

Returns: the JSON payload returned by POST /v1/retrieve/augment, typically including:

  • documents
  • uri
  • document
  • metadata when requested
  • processingMetadata when requested
  • provenance when requested

Error Behavior

The tools follow a fail-fast contract:

  • Missing retrieveQuery or augmentRequest returns a descriptive tool error.
  • Invalid JSON in either argument returns a descriptive tool error.
  • HTTP failures from MarkLogic Server are returned as tool errors with the underlying message.
  • The agent layer does not silently rewrite request bodies, except for the uris → URIs normalization in Augment.
Alert