Powered by Zoomin Software. For more details please contactZoomin

MarkLogic MCP Server

Table of Contents

Architecture

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 MCP Server enables AI agents within MCP clients to search and retrieve content stored in MarkLogic Server databases. MarkLogic MCP Server connects the MCP client to the MarkLogic Retrieval API (MRA). It exposes MCP tools, translates tool invocations into MRA requests, and returns the results to the client.

System components

The architecture consists of four primary components:

MCP client

An MCP client is an AI-enabled application, such as VS Code with GitHub Copilot or Claude, through which a user submits a question. The MCP client discovers the tools that the MarkLogic MCP Server exposes and invokes them during a chat or agent workflow.

MarkLogic MCP Server

MarkLogic MCP Server is the MCP-facing intermediary between the MCP client and MarkLogic Server:

  • It provides the MCP endpoint used by the MCP client.
  • It handles authorization pass-through and OAuth flows.
  • It exposes the RetrieveDefinition, Retrieve, and Augment tools.
  • It routes tool invocations through the corresponding MCP Server modules.
  • It forwards requests to the corresponding MRA endpoints.

MarkLogic MCP Server does not search content, rank results, or enforce document permissions.

MarkLogic Retrieval API (MRA)

MRA is a set of REST endpoints and supporting modules deployed in MarkLogic Server:

  • It reports the retrieval capabilities configured for the deployment.
  • It performs full-text and vector retrieval.
  • It applies labels and filters.
  • It scores and merges search results.
  • It retrieves full documents or selected document fragments.

MRA does not communicate directly with the MCP client.

MarkLogic Server

MarkLogic Server is the data and security platform that hosts the MRA and the searchable content:

  • It provides the REST app server.
  • It stores content in databases.
  • It provides search capabilities through indexes, schemas, and TDE views.
  • It provides retrieval configuration.
  • It provides security through roles and document permissions.

Tool and endpoint mapping

MarkLogic MCP Server exposes three tools. Each tool maps to an internal MCP Server module, which forwards the request to an MRA endpoint.

MCP Client Purpose MCP Tool MCP Server Module ID MRA Endpoint
To retrieve available labels, filters, and metadata RetrieveDefinition retrieve-definition GET /v1/retrieve/definition
To retrieve candidate document URIs Retrieve retrieve POST /v1/retrieve
To retrieve full document content for selected URIs Augment augment POST /v1/retrieve/augment

Request path

Requests and results follow this path:

MCP client
    |
    | MCP over HTTP
    v
MarkLogic MCP Server
    |
    | HTTP
    v
MarkLogic Retrieval API in a MarkLogic REST App Server
    |
    v
MarkLogic Server content, indexes, schemas, and configuration

The MCP client communicates with MarkLogic MCP Server, not directly with MRA. MarkLogic MCP Server converts the selected tool invocation into a request to the corresponding MRA endpoint. MRA performs the operation in MarkLogic Server, and the result returns to the MCP client through MarkLogic MCP Server.

Tool discovery flow

  1. The MCP client connects to the MarkLogic MCP Server endpoint at /api/v1/agent/mra-agent/session/<session-id>/mcp.
  2. MarkLogic MCP Server reports its available tools.
  3. The MCP client makes the tools available to the AI agent or user workflow.

Retrieval workflow

A typical retrieval workflow uses the tools in this order:

  1. The MCP client invokes RetrieveDefinition to discover the labels, filters, schemas, vector metadata, and other retrieval information available for the deployment.
  2. The MCP client invokes Retrieve with text, labels, filters, vectors, or a combination of these inputs. MRA returns matching document URIs and result information.
  3. The MCP client or its AI agent selects relevant URIs and invokes Augment to retrieve full document content or selected document fragments.
  4. The MCP client uses the returned content to construct a response for its user.

Component boundaries

The separation between components helps identify where to configure or troubleshoot behavior:

  • Tool discovery and invocation: MCP client and MarkLogic MCP Server.
  • MCP transport, routing, sessions, and authorization behavior: MarkLogic MCP Server.
  • Search, filtering, scoring, merging, and document retrieval: MRA.
  • Content, indexes, database configuration, roles, and document permissions: MarkLogic Server.

For example, if a tool is not visible, then inspect the MCP client and the MarkLogic MCP Server configurations. If a tool is visible but returns unexpected search results, then inspect the MRA and the MarkLogic Server retrieval configurations.

Deployment topologies

Local development

A local development environment can include these components:

  • The MCP client on the user's workstation.
  • The MarkLogic MCP Server container on the same workstation, typically exposed on port 8088.
  • MarkLogic Server on the same host, in a container, or at an address reachable from the MarkLogic MCP Server container.

Shared environment

A shared environment can include these components:

  • MarkLogic MCP Server behind an internal or externally accessible URL.
  • MarkLogic Server in a protected network segment.
  • TLS termination and an OAuth identity provider, when OAuth is configured.

Regardless of topology, the MCP client connects to MarkLogic MCP Server, and MarkLogic MCP Server connects to the MarkLogic REST app server that exposes the MRA.

Alert