Quick start

Save PDF

Last Updated: September 9, 2026
5 minute read

Documentation

Overview

This quick start guide provides a streamlined deployment process that assumes that you have an existing MarkLogic Server instance with data already loaded and a MarkLogic REST app server already configured.

System requirements

To deploy the MarkLogic Retrieval API and MarkLogic MCP Server, you need the following prerequisites to ensure compatibility between the container platform, MarkLogic Server, and the deployment automation tooling:

A container platform with Docker CLI (docker command) compatibility like Docker Desktop or Rancher Desktop
An instance of MarkLogic Server (version 11.0+) with the REST app server used by MCP configured to the content database and its attached schemas database. Data must already be loaded. If you plan to use vector search, the searchable data must also have vector embeddings in configured TDE vector columns.
Gradle to deploy MRA as part of your REST app server.

Release distribution

MarkLogic MCP Server is distributed as two independent artifacts, published in two separate locations:

MarkLogic MCP Server container image: A prebuilt Docker image published to Docker Hub. Pull it directly with docker pull progressofficial/marklogic-mcp-server:<tagname> or view it on Docker Hub; no download or extraction is required. See Image Tags for the current list of available images and tags.
Deployment package: A ZIP archive containing the MRA deployer and example configuration files, published on the marklogic-mcp-deployer GitHub releases page. This archive does not contain the MarkLogic MCP Server container image or MCP server source; pull the container image separately from Docker Hub.

Distributing these independently lets you pull an updated container image and download an updated deployment package on separate schedules, without one release blocking the other.

Installation overview

Before the MarkLogic MCP Server can operate, the MarkLogic Retrieval API (MRA) must be installed into an existing MarkLogic REST app server.

This installation takes 10–15 minutes for an experienced operator with existing infrastructure in place:

Pull the MarkLogic MCP Server container image.
Download the deployment package.
Extract the deployment package.
Deploy the MarkLogic Retrieval API to MarkLogic Server.
Configure the MarkLogic MCP Server.
Start the MarkLogic MCP Server.
Connect an MCP client.
Verify operation.

Pull the MarkLogic MCP Server container image

Pull the prebuilt MarkLogic MCP Server image from Docker Hub:

docker pull progressofficial/marklogic-mcp-server:<tagname>

The image is now available in your local Docker image store, tagged progressofficial/marklogic-mcp-server:<tagname>. You can also see the image by using the docker images command.

Download the deployment package

Download the deployment package from the marklogic-mcp-deployer GitHub releases page.

Each release contains a single artifact:

marklogic-mcp-<version>.zip: The deployment package used to install the MarkLogic Retrieval API into MarkLogic Server and configure the MarkLogic MCP server. It does not contain the MarkLogic MCP Server container image; pull that separately from Docker Hub (see Pull the MarkLogic MCP Server container image).

Extract the deployment package

Extract the contents of the ZIP file, which creates this folder structure:

marklogic-mcp-<version>
├───examples
│   └───marklogic-mcp
│
└───mra-deployer

examples/marklogic-mcp: Contains sample .env, config.yaml, and docker-compose.yaml files used to start the MarkLogic MCP server container.
mra-deployer: Contains the deployer to run against your existing MarkLogic Server to install the MRA modules, roles, and configuration. This is a set of ml-gradle artifacts that you can add to your existing project.

Deploy the MarkLogic Retrieval API to MarkLogic Server

The mra-deployer directory contains everything needed to install MRA into your existing MarkLogic Server instance. No separate MarkLogic Server installation is required.

Note:

This procedure uses Gradle. If you prefer bash or Python, see BASH-QUICK-START.md and PYTHON-QUICK-START.md in mra-deployer/ for equivalent scripted deployment options.

Access the gradle.properties file:

cd marklogic-mcp-<version>/mra-deployer
vi gradle.properties

In gradle.properties, set these parameters at a minimum:

mlAppName=<your-app-name>

# MRA needs to add files to your modules and schemas databases.
# You are only required to set these if they don't follow standard ml-gradle naming conventions.
mlModulesDatabaseName=<your-modules-db>
mlSchemasDatabaseName=<your-schemas-db>

mlHost=<your-marklogic-host>
mlRestPort=<your-rest-port>
mlUsername=<admin-user>
mlPassword=<admin-password>
mlAuthentication=<app-server-authentication>

Deploy your app with this command:
```
./gradlew installMra -i
```
Using the MarkLogic Server Admin Interface, Query Console, or Management REST API, verify that these MRA configurations have been deployed:
- Roles: Check that these roles exist:
  - mra-internal
  - mra-reader
  - mra-writer
- Modules: Check your app server's configured modules database for these URIs:
  - /MarkLogic/rest-api/endpoints/augment.sjs
  - /MarkLogic/rest-api/endpoints/retrieve.sjs
  - /MarkLogic/rest-api/endpoints/retrieveDefinition.sjs
- Schemas: Check your content database's configured schema database for this URI:
  - /marklogic-retrieval-api/retrieveConfig.json
Or, access http://localhost:8003/v1/retrieve/definition with your web browser. You should get a valid JSON response with default information and auto-extracted information from your database settings:
```
{
  "description": "No description configured for this deployment. ...",
  "labels": [...],
  "filters": [...],
  ...
}
```
Add the mra-reader role to your existing application's reader role so that users can query through MRA.

Configure the MarkLogic MCP server

cd marklogic-mcp-<version>/examples/marklogic-mcp
cp .env.example .env

Review and edit as needed:

.env
- Entries for configuration are described as part of the environment file.
- Set MARKLOGIC_MCP_IMAGE to the image reference you pulled. See Pull the MarkLogic MCP Server container image.
config.yaml
- Update all entries under workflows so that marklogic_url and auth_method map to your instance of MarkLogic REST app server with MRA installed.
- If you want MCP clients to authenticate through OAuth, then set mcp_auth.enabled: true and fill in protected_resource_metadata_url, authorization_server, jwks_url, and scopes_supported for your identity provider. Leave it false for the default basic or digest auth-to-MarkLogic Server passthrough behavior.
docker-compose.yaml
- Adjust exposed ports if needed.

Start the MarkLogic MCP server

Start the server with this command:
```
docker compose up -d
```
These lines appear:
```
[+] Running 2/2
 ✔ Network marklogic-mcp_default            Created ...
 ✔ Container marklogic-mcp-marklogic-mcp-1  Started ...
```
Note:
- If you re-run this command, then the same container is restarted.
- If the container is already running, then it is reported as already running.
Verify that the container is running by accessing the configured protected_resource_metadata_url (http://localhost:8088/.well-known/oauth-protected-resource) using your web browser. You will get the following response:
```
{
  "resource": "http://localhost:8088",
  "scopes_supported": [],
  "authorization_servers": []
}
```
Note:

resource changes depending on your configured config.yaml and docker-compose.yaml.

Connect an MCP client

Connect an MCP client to MarkLogic MCP Server. For client configuration details, see Configure an MCP client.

Base64-encode the credentials for a MarkLogic Server reader user, and configure your MCP client with the ephemeral session endpoint like this:

echo -n "<username>:<password>" | base64

In your application's MCP configuration, add this entry:

"MarkLogicMCP": {
  "url": "http://localhost:8088/api/v1/agent/mra-agent/session/ephemeral/mcp",
  "type": "http",
  "headers": {
    "Authorization": "Bearer <base64-credentials>"
  }
}

Verify operation

MarkLogic MCP Server is installed and running. You can now ask your MCP client questions grounded in the documents indexed in your MarkLogic Server database, and it replies and cites the sources that it used.

For detailed background on each component, see Concepts.

For troubleshooting and production hardening guidance, see Operations.

Next steps

Once the quickstart is complete:

Configure an MCP client → Configure an MCP client
Learn how to configure MCP server connectivity and OAuth → Configuration Guide
Review config.yaml Reference → config.yaml Reference
Customize retrieval search behavior → Retrieve Config Guide
Complete API reference → Retrieval API Reference

Key documentation

config.yaml Reference: Detailed config.yaml options
Retrieve Endpoint: Complete /v1/retrieve endpoint reference
Augment Endpoint: Document retrieval by URI
Retrieve Config: Search configuration discovery
Filters: Constraint-based filtering