Powered by Zoomin Software. For more details please contactZoomin

MarkLogic MCP Server

Table of Contents

API reference

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

MarkLogic Retrieval API (MRA) is the component that performs search and document retrieval inside your MarkLogic server. It is separate from the MarkLogic MCP Server: the MCP Server routes tool calls from your MCP client to the Retrieval API, but the Retrieval API does the actual work against your data.

The API provides three endpoints: /v1/retrieve/definition to discover what is searchable, /v1/retrieve to search, and /v1/retrieve/augment to retrieve full document content by URI. If you are new to this API, complete the Quick Start before reading the reference material below.

Documentation Index

Core API

definition.md

Search configuration and discovery endpoint

Documents the /v1/retrieve/definition endpoint, which returns available search capabilities including collections, filters, document schemas, and vector embeddings.

Topics covered:

  • Discovering available collections (labels)
  • Available filters (Value, Word, Range, and View types)
  • Document schemas
  • Vector metadata (embedding models, dimensions)
  • Using definition data to build search UIs
  • Code examples (Python, JavaScript, cURL)

Use this to dynamically discover what search capabilities are available.

retrieve.md

Primary search endpoint documentation

Complete reference for the /v1/retrieve endpoint, the main search interface for the MarkLogic Retrieval API. Covers text search, vector search, filters, collection labels, and all request parameters.

Topics covered:

  • Text search with full-text indexing
  • Phrase search with double quotes for exact matching
  • Vector similarity search using embeddings
  • Constraint-based filters (Value, Word, Range, View)
  • Collection labels (MustHave/MustNotHave)
  • TopK result limiting and totalMatches count
  • Request/response formats
  • Search behavior and performance

Start here if you're implementing search functionality.

Search Query Best Practices: When you use /v1/retrieve before augmenting, remember that words in the text field are AND-ed by default. That means all terms must appear in a matching document, which can be very restrictive. To maximize recall, connect synonyms and related terms with OR.

  • Good: "GLP-1 OR liraglutide OR semaglutide OR glucagon-like peptide"
  • Too narrow: "GLP-1 glucagon-like peptide glucose mice" (ANDs all terms)

Recommended workflow for complex questions:

  1. Decompose your question into concept groups (e.g., drug names / outcomes / mechanisms).
  2. Issue one Retrieve call per concept group using OR within each group.
  3. Collect all unique document URIs across calls.
  4. Pass the deduplicated URIs to Augment to fetch full content.
  5. Filter augmented documents for relevance before synthesizing.

augment.md

Document retrieval by URI

Complete reference for the /v1/retrieve/augment endpoint, which retrieves full document content by URI. Use after searching to get complete documents.

Topics covered:

  • Retrieving documents by URI
  • Batch document retrieval
  • Response format with full content
  • Error handling
  • Code examples

Use after /v1/retrieve to get full document content.

Filter and Configuration

filters.md

Comprehensive filter usage guide

Detailed guide to using constraint-based filters in search requests. Covers all filter types with practical examples.

Topics covered:

  • Value filters (exact matches)
  • Word filters (tokenized, case-insensitive word matches)
  • Range filters (dates, numbers)
  • View filters (TDE/Optic joins)
  • Filter combination logic (AND)
  • Common filter patterns
  • Troubleshooting filters

Essential for advanced search queries with filtering.

retrieve-config.md

Configuration file reference

Technical reference for the retrieveConfig.json configuration file that defines search capabilities. For system administrators and developers setting up the API.

Topics covered:

  • Configuration file structure
  • Document schema references
  • Vector metadata configuration
  • Extraction XPath configuration
  • Relationship to /v1/retrieve/definition
  • Configuration workflow
  • Troubleshooting

For system setup and configuration - not needed for API consumers.

Documentation Conventions

Throughout these guides:

  • 🔹 Code examples are provided using cURL.
  • 🔹 Response formats show actual API structures with field descriptions.
  • 🔹 ⚠️ Warnings indicate features that are planned but not yet implemented.
  • 🔹 Related Documentation links appear at the end of each guide.
Alert